Component Services Administration Help

With the Component Services administrative tool you can configure and administer COM components and COM+ applications. This guide provides information on using the Component Services administrative tool to perform administrative tasks such as configuring your system, installing applications, and configuring and monitoring services used by your applications. Use the links in this topic to get more information about administering Component Services.

Topic | Description
Guide to Administering Component Services | Provides an introduction to basic administrative concepts, as well as an "administrative life cycle" that suggests categories for grouping administrative tasks.
Component Services Console Tree | Offers descriptions of the items visible in the console tree.

Administrative Areas

In the course of administering Component Services, your tasks will typically fall into the areas in the following list. Use these links to get more information about each.

Topic | Description
Configuring the System for Component Services | Describes tasks you must perform after you install Component Services, and before you can use the Component Services administrative tool over your network.
Installing COM+ Applications | Introduces client- and server-side COM+ application deployment.
Administering Application Security | Provides an overview of Component Services security administration, along with links to more information on setting attributes to enforce security.
Administering Distributed Transactions | Introduces distributed transaction administration, providing links to concepts and tasks on configuring your system to use MS DTC, view transaction statistics, and resolve transaction states.
Administering Queued Components | Introduces Queued Components, with which a COM component can request services from another component even when that component is unavailable or offline.

In addition to those performing administrative tasks, component developers can also use the Component Services administrative tool to configure routine component and application behavior, such as participation in transactions and object pooling. For details about application development with Component Services, see COM+ (Component Services) under "Component Services" in the Microsoft Platform SDK. For links to the Platform SDK, see COM+ Programming Topics in this guide.


COM+ Programming Topics

The topics in this Component Services administration guide cover only administrative settings you can make with the Component Services administrative tool. You will find development settings discussed in COM+ (Component Services), under Component Services in the Microsoft Platform SDK. If you don't have the Platform SDK installed, see the MSDN Web site to view or install it.


Guide to Administering Component Services

You can deploy and administer COM+ applications in two ways. You can use the Component Services administrative tool (a Microsoft Management Console snap-in) or you can write scripts to automate these processes.

Component Services Administrative Tool

This guide explains how to use the Component Services administrative tool to administer computers and COM+ applications. With the Component Services administrative tool you can configure and administer COM components and COM+ applications. Use the following links for an overview of administering Component Services.

Topic | Description
Component Services Administration Concepts | Introduces concepts key to understanding the role of Component Services administration.
Administrative Life Cycle for Component Services | Provides an "administrative life cycle" that suggests categories for grouping administrative tasks.

To start the Component Services administrative tool
  • On the Start menu, point to Programs, point to Administrative Tools, and then click Component Services.

Scripts for Component Services Administration

In addition to using the Component Services administrative tool to perform administrative tasks, you can also automate any of these tasks by writing code that uses administration objects provided through the COMAdmin Library DLL. For a description of how to use these objects, see Automating COM+ Administration under Creating and Configuring COM+ Applications in the Component Services section of the Microsoft Platform SDK.


Component Services Administration Concepts

Most Component Services administrative tasks involve shepherding completed development efforts into use on the network, and ensuring high performance and security for the deployed applications and components. Within this role, the tasks you perform will depend on the type of application you're working with and the services that application uses. This topic provides an overview of application types and the services they use.

Tasks Described in this Guide

Note that the topics in this Component Services administration guide cover only a portion of the settings you can make with the Component Services administrative tool. Settings not covered by this guide should only be made by someone with thorough knowledge of the component's or application's implementation. Typically, these settings are made by the developer before the application is delivered to be installed and deployed.

You will find development settings discussed in COM+ (Component Services), under Component Services in the Microsoft Platform SDK. For a link to the Platform SDK, see COM+ Programming Topics in this guide.

Application Types

You can think of applications you administer with the Component Services administrative tool as falling into one of two categories: COM applications and COM+ applications. These terms are used in this guide where settings may vary depending on the application type.

The idea of COM applications is not at all new — it's simply the term used to refer to groups of COM components developed to work together. A COM application example is Microsoft Excel, which consists of a primary executable and accompanying application extension DLLs for spell checking, Visual Basic functionality, and so on.

COM+ applications, on the other hand, are groups of COM components developed and configured together to make use of Component Services such as queuing, role-based security, and so on. As a result, these are discussed much more frequently in this guide than COM applications. Some of what differentiates a COM+ application is written into the component code, and some is defined through the Component Services administrative tool.

In addition, COM+ applications can be divided into two types, each with distinct administrative needs. These are COM+ server applications and COM+ library applications. Server applications run in their own process space; for example, a server application might consist of a group of DLLs that encapsulate payroll processing. Library applications consist of components developed to run in another host's process; for example, in a library application, you might group DLLs that provide services to other application components, and that can share security characteristics of those components.


Administrative Life Cycle for Component Services

You can think of administrative tasks performed with the Component Services administrative tool as falling into the following four broad categories:

  • Configuring your system for Component Services
  • Making initial services settings
  • Installing and configuring applications
  • Monitoring and tuning component services

Note While this topic suggests tasks that are necessary or common, there are others you might perform as the need arises. For a more complete view, be sure to read the documentation for the areas you will be administering.

Configuring Your System for Component Services

When you are getting started with Component Services, there are a few customization tasks you must perform before you can use the services with your network. For example, you must start by setting access to the underlying application that responds to settings and tasks you perform in the Component Services administrative tool. For more information on these getting started tasks, see Configuring the System for Component Services.

Making Initial Services Settings

Once you have done basic Component Services configuration for the characteristics of your network, your next step might be to adjust settings specific to the kinds of applications and services you will be using on the network.

The following list includes a few examples of settings you might make to computers on your network.

  • To ensure security for components that aren't configured into COM+ applications — in other words, they're COM components deployed independently, or COM applications — you may need to make specific COM security settings for those computers. (COM+ applications, on the other hand, can be designed to take advantage of role-based security.)

    For more information, see COM Security Settings.

  • If your applications will use distributed transactions, you should specify whether MS DTC will start manually or automatically on each computer that will run it. Also, if transactions will be used with Windows Clustering, you must configure the network appropriately.

    For more information, see MS DTC Configuration.

Installing and Configuring COM+ Applications

Before a COM+ application can be used, you must configure it with settings specific to the services it will use, then install its client- and server-side portions to computers on the network.

The following list includes a few examples of tasks you might perform to install and configure COM+ applications.

  • Before you can make settings that will govern how the COM+ application behaves on the network, you must install the application to a staging machine where you can configure it.

    For more information, see Staging and Production Computers.

  • To ensure that the application participates appropriately in your network's security scheme (in other words, both access to the application and its access to other resources are appropriate to your needs), you may need to add users to the application's roles and set the application's security identity.

    For more information, see Role-Based Security and Application Identity.

  • Once you have configured the COM+ application with respect to security and the services it will use, you must deploy its client- and server-side portions to production computers across your network.

    For more information, see Installing COM+ Applications.

Monitoring and Tuning Component Services

Once you have deployed components that use Component Services, you can track those services to watch for performance enhancement opportunities and to handle failures. In some cases, changes you make to these settings — particularly to achieve more thorough monitoring — may actually decrease performance. Be sure to read the documentation in the area you are configuring.

The following list gives examples of tasks you might perform to monitor your components and applications.

  • When a new version of a COM+ application is available, upgrading to the new version is a matter of removing the older version and installing the new one.

    For more information, see Installing COM+ Applications.

  • To enhance your control of security, you can use reference tracking to make additional security checks and keep track of additional information to keep objects from being accidentally or maliciously released too early.

    For more information, see Reference Tracking.

  • If applications participate in distributed transactions, you can monitor performance by viewing transaction status, messages, and statistics. Also, you may be able to increase system performance by changing the size or location of the log file that stores transaction statistics.

    For more information, see Monitoring MS DTC Performance and Log File Management.


Component Services Console Tree

You can use the console tree of the Component Services administrative tool to view the applications, components, and security roles you can administer. This topic describes the categories of items you will see in the console tree.

Computer

Contains MyComputer and other computers that have been added by an administrator.

My Computer

By default, MyComputer corresponds to the local computer on which the Component Services administration tool is installed.

Applications

Corresponds to the applications installed on this computer. You can change properties of an application by right-clicking on the application and then clicking Properties. For more information on installing applications, see Installing COM+ Applications.

Components

Corresponds to the components installed in a COM+ application. You can change properties of a component by right-clicking on the component and then clicking Properties.

Roles

Corresponds to the roles available for a COM+ application. You can change properties of a role by right-clicking on the role and then clicking Properties.

Interfaces

Corresponds to the interfaces available in a component. You can change properties of an interface by right-clicking on the interface and then clicking Properties.

Methods

Corresponds to the methods available from interfaces. You can change properties for a method by right-clicking on the method and then clicking Properties.

Users

Corresponds to the users belonging to a role. You can add and remove users by right-clicking on the User folder, clicking New, and then clicking User. You can delete users by right-clicking on a user and then clicking delete.

Distributed Transaction Coordinator

Contains the Transaction List to display current transactions in which the computer is participating, and Transaction Statistics to display information on the transactions. For more information on the Distributed Transaction Coordinator, see Administering Distributed Transactions.

Transaction List

Displays the current transactions in which this computer is participating. This includes transactions for which status is in doubt, or which have remained in the same state for the transaction timeout period specified on the Options tab of the computer property sheet.

Transaction Statistics

Displays transaction information, such as performance, types, speed, and maximum and minimum response time for the transactions in which a computer participates.


Configuring the System for Component Services

After you install Component Services, you must perform initial system configuration. Configuration involves enabling administrator control by setting security for the System application. It also includes configuring Component Services to recognize your network by making computers visible to Component Services and enabling component communication across machine boundaries by configuring distributed COM. These configuration requirements are crucial to proper installation of Component Services.

Topic | Description
System Configuration Concepts | Provides a list of tasks for system configuration, along with links to step by step descriptions.
System Configuration Tasks | Provides links to step by step descriptions.

Before You Go On

Depending on your system's needs, it may be necessary to do further configuration of Component Services than is described in the topics of this section. Although you may be able to configure the following properties at a later date, it is important to be aware of them early.

  • If you intend to have local Component Services participating in distributed transactions, you will need to configure Microsoft Distributed Transaction Coordinator (MS DTC). For more information see Administering Distributed Transactions.
  • If enhancing system scalability is a goal for you, you can configure Component Services to shut down application processes that are not being used.


System Configuration Concepts

Once you have installed Component Services, you must perform the following initial system configuration.

Enabling Administrator Control by Setting Security

The System application manages configuration and deployment within Component Services. To guard access to this important application, you must define who can administer the environment. This is necessary in order to make any changes to your Component Services configuration, including installing an application or adding a computer.

The System application uses role-based security within two roles, Administrator and Reader. Members of the Administrator role have read and write access to the System application. They can add, change, or delete any of the settings in the Component Services administrative tool. You must assign at least one user to the Administrator role or no one will be able to administer Component Services. Members of the Reader role have read-only access to the System application. They can view settings in the Component Services administrative tool, but they cannot change, add, or delete anything.

For instructions on setting administrative security on the System application see Setting Security. For additional information on security see Administering Application Security.

Making Computers Visible to Component Services

Any computer you want to administer for Component Services should be added to the console tree of the Component Services administrative tool. Unless your computer is visible to the Component Services administrative tool, you not be able to set security or install applications. For instructions on adding computers to Component Services, see Making Computers Visible to Component Services.

Configuring Distributed COM

The distributed COM (DCOM) wire protocol handles all network communication between COM components running on separate computers. You must enable DCOM for each computer with COM components that communicate with others across the network. Although disabling DCOM will have no effect on communication between components on the same computer, all communication will be disabled between components on separate computers. For instructions on enabling component communication across machine boundaries see Enabling or Disabling Distributed COM.

Note The Component Services administrative tool requires the Microsoft Distributed Transaction Coordinator (MS DTC) service to be running. If MS DTC is stopped and you attempt to change any settings using the Component Services administrative tool, the MS DTC service will be restarted. Should you get errors when attempting to use the Component Services administrative tool, verify that MS DTC is started, and if not, restart it. For more information on starting and stopping MS DTC, see Starting and Stopping MS DTC.


System Configuration Tasks

Once you have installed Component Services, you must perform initial system configuration.

  • Setting Security.
  • Making Computers Visible to Component Services.
  • Enabling or Disabling Distributed COM.

For overview information on these tasks, see System Configuration Concepts.


Setting Security

The System application manages the configuration and deployment within Component Services. In order to be able to make any changes to the system, such as installing an application or adding a computer, security must be set to define who can administer the environment. The following procedure describes how to enable security on the System application.

Caution If you enable security on the System application, you must assign at least one user to the Administrator role. If you do not, no one will be able to administer Component Services and you must reinstall Component Services.

To enable security on the System application
  1. In the console tree of the Component Services administrative tool, expand the COM+ Applications icon.
  2. Expand the System Application icon.
  3. Expand the Roles icon.
  4. Expand the Administrator icon.
  5. Follow steps 3-5 of Assigning a User Account or Group to a Role, assigning users or groups who should have administrative access to Component Services.
  6. Restart the computer for the changes to take effect.

You may need to remove a user from the Administrator role of the System application. For detailed instructions see Removing a User Account or Group from a Role.


Making Computers Visible to Component Services

If you have sufficient privileges on a remote computer, you can manage its COM+ applications and monitor its transactions from the Component Services administrative tool on your own computer. Use the following instructions to add computers to the console tree of your local Component Services administrative tool.

To add a computer to the Component Services administrative tool hierarchy
  1. In the console tree of the Component Services administrative tool, right-click the Computers icon, point to New, and then click Computer.
  2. In the Add Computer dialog box, type the name of the computer to add, or click Browse to select from a list of available computers.
  3. Click OK.

After you have added the computer to the console tree, an icon representing it appears in the details pane. Using the Component Services administrative tool, you can now manage objects on the remote computer in the same way you manage objects on the local computer.

When you no longer want a computer to be part of your Component Services environment, you can remove it from the Component Services administrative tool hierarchy.

To remove a computer from the Component Services administrative tool hierarchy
  1. In the console tree of the Component Services administrative tool, click the Computers icon.
  2. In the details pane, select the computer or computers you want to remove.
  3. Press the Delete key.


Enabling or Disabling Distributed COM

If the computer containing Component Services is part of a network, Component Services needs the DCOM wire protocol to communicate with COM components on other computers. You can disable DCOM, but doing so will disable communication with components on other computers.

Warning If you disable DCOM on a remote computer, you will not be able to remotely access that computer afterwards to enable DCOM again. To enable DCOM again, you will need physical access to that computer.

To manually enable or disable DCOM
  1. In the console tree of the Component Services administrative tool, right-click the computer for which you want to disable (or enable) DCOM, and then click Properties.
  2. Click the Default Properties tab.
  3. Clear the Enable Distributed COM on this computer check box to disable DCOM. (To enable DCOM, select this check box.)
  4. Click OK.


Installing COM+ Applications

Many of the tasks performed by system administrators relate to installing server applications on staging and production computers, installing application proxies on client computers or server to server, and removing or updating applications. With Component Services, much of this work can be performed through the Component Services administrative tool. All of these tasks can also be automated through the Windows Scripting Host.

Use the following links to get background and task information.

Topic | Description
Installation Concepts | Provides an introduction to COM+ application installation.
Installation Tasks | Provides links to tasks associated with installing COM+ applications.

For a description of COM+ applications, see Component Services Administration Concepts.

Before You Go On

  • Installing a COM+ application typically involves working with components and pre-built COM+ applications on a staging computer used to develop and test the application. For more information on staging computers, see Staging and Production Computers. Before you begin the installation process, you typically will have used the Component Services administrative tool (running on the staging computer) to configure security, including setting identities and assigning users to roles. For more information, see Security Administration Tasks.

You may also want to set the server process shutdown so that there is a timeframe in which the server process will be terminated after remaining idle.


Installation Concepts

When you install a COM+ application, you make the completed application and its components available for use on a computer or over the network. Unlike traditional application installation, the process for installing a COM+ application typically includes two fundamental steps: exporting client- and server-side installation files, and then using these to install proxy and application information to client and server computers on the network.

For more information, see the following topics.

Topic | Description
Before Installing Applications | Notes configuration and security considerations having to do with installation.
COM+ Application Installation Overview | Provides an overview of installation scenarios, along with links to step-by-step details.
Staging and Production Computers | Introduces the concept of separate computers for development and testing, versus computers for final application deployment.
Server-Side Installation for COM+ Applications | Provides an overview and caveats related to installing server-side components.
Client-Side Installation for COM+ Applications | Provides an overview and caveats related to installing client-side components.


Before Installing Applications

Installing applications through the Component Services administrative tool requires certain system security permissions. For information on security implications when installing COM+ applications, see Setting Security.

In addition to security, other configuration tasks must be completed before installing COM+ applications through the Component Services administrative tool. For more information on configuring the Component Services environment, see Administrative Life Cycle for Component Services.


COM+ Application Installation Overview

COM+ applications are often installed as part of a larger application, using a regular setup program provided by the application vendor or an in-house developer. However, you may occasionally need to manually install and configure COM+ applications.

Manually installing a COM+ application includes these steps:

  1. Configuring the COM+ application for a specific target environment.
  2. Exporting environment-specific client- and server-side installation files.
  3. Installing a configured or unconfigured COM+ application or a COM+ application proxy.

Depending on how the application vendor or developer chooses to provide the application, not all of these steps may be required. For more information, refer to the documentation provided with the application.

Typically, COM+ applications can be either:

  • Fully-configured applications provided by the developer or application administrator.
  • Unconfigured or partially-configured applications provided by the developer or ISV.

Fully-configured applications are often used for applications developed in-house, in which the developer or an application administrator has full knowledge of the target environment (user accounts/groups, server names, and so on). The developer will have configured and exported the application so that an administrator need only install the application on the target system.

Unconfigured or partially-configured applications are often off-the-shelf applications that are purchased from a third party. Sometimes the application vendor will provide a regular installation program that guides you through the required steps. If such an installation program is not provided, you must install and configure the COM+ application. Configuring the COM+ application is often performed on a staging computer rather than on the production computer. In this case, you must re-export the configured COM+ application and a COM+ application proxy, then install it on the production computers. For more information on using staging computers, see Staging and Production Computers.

For step-by-step details on installing applications, see Installation Tasks.

For an overview of configuration for COM+ applications, see Administrative Life Cycle for Component Services.

Updating COM+ Application Versions

As they mature and become dated or are no longer used, you will need to remove COM+ applications and/or update COM+ applications. If you want to upgrade a COM+ application, you must first delete the previously-installed version and then install the updated application.

For step-by-step details, see Removing COM+ Applications and Installing COM+ Applications.


Staging and Production Computers

You may choose to install and test applications on staging computers that allow you to simulate scenarios that are likely to occur after applications are deployed on production computers used by others on the network.

In some cases, changes between staging and production environments are necessary. For example, the security configuration might be different between environments. In other cases, the configuration is identical and the only difference is that the staging server is not publicly accessible. In the latter instance, you may want to replicate the applications, moving a validated set of applications and their configuration from a staging to a production computer.

For more information on replication, see Replicating COM+ Applications.

Staging computers can also be used to manage versioning and to update components. Rather than changing configurations or updating individual components on a production computer, you can modify the application, test it on a staging computer, and then export it as a unit to be installed on the production computer.


Server-Side Installation for COM+ Applications

A COM+ server application consists of a server application file (.msi). Use the Component Services administrative tool or the Windows Installer to install the COM+ application.

If a component in a COM+ application requires the installation or configuration of other resources — database connections, data or text files, Internet Information Services (IIS) virtual root configuration, and so on — these must be installed through mechanisms outside of the Component Services administrative tool. For additional information, see the documentation provided by the application vendor.

For step-by-step detail on application installation, see Installing COM+ Server Applications.


Client-Side Installation for COM+ Applications

Once a COM+ server application is installed on a computer, it may be necessary to access the application remotely by using DCOM or Message Queuing. See the documentation provided by the application vendor for more details.

If an application is to be accessed remotely, you can use the Component Services administrative tool to export a COM+ application proxy. The application proxy (.msi) file contains the registration information needed to remotely access classes in a COM+ server application from a client computer through DCOM. Using this file, you then install the COM+ application proxy on the site's client computers.

It is possible to create an application proxy that will access a different server than the computer from which it was exported. This is useful when the application proxy for a production computer needs to be exported from a staging computer. To change the server name, use the Options tab of the Computer Properties page in the Component Services administrative tool and enter the correct application proxy remote server name (RSN).

For step-by-step details on exporting and installing application proxies, see Exporting COM+ Application Proxies and Installing COM+ Application Proxies.


Installation Tasks

The following lists COM+ application installation tasks you may need to perform. These tasks will typically be done in the order given here.

  • Exporting COM+ Server Applications
  • Installing COM+ Server Applications
  • Exporting COM+ Application Proxies
  • Installing COM+ Application Proxies
  • Removing COM+ Applications
  • Replicating COM+ Applications


Exporting COM+ Server Applications

You can use the Component Services administrative tool to export a COM+ server application for installation on one or more other server computers. For example, you can use the Component Services administrative tool to copy a COM+ application from a staging computer, on which the application was developed and tested, to a production computer at an individual site.

To export a COM+ server application
  1. In the console tree of the Component Services administrative tool, click the application you want to export.
  2. Right-click the application, and then click Export.
  3. In the initial dialog box for the COM Application Export Wizard, click Next.
  4. In the Application Export Information dialog box, enter the full path of the application file to be created, or click Browse to search for an existing file or directory.

    An .msi file with the name you specify will be created when you have finished with the wizard. This file contains all the necessary information for the COM+ application.

  5. Under Export as, click Server application - Install this application onto other machines.
  6. If you want to include any users that you have assigned to roles for the application, select the Export user identities with roles check box.

    Use this option only if you plan to install the application on a computer that is running in the same Windows 2000 security domain as the computer from which you are exporting the application. If not, the user IDs assigned to roles may be invalid, causing errors when you attempt to install the application.

    Additionally, be careful when installing the application on a computer running a different language version of Windows 2000 from that on the computer from which you are exporting the application. Some user and group names such as "Administrators" will be localized on the target computer. These users will need to be re-added to the role before they will be able to access the application on the target computer.

  7. Click Next.
  8. In the closing dialog box, click Finish.

Note Application locks against changes or deleting will be exported with the application.

Important If a component's class ID (CLSID), type library identifier (TypeLibId), or interface identifier (IID) change after you have exported an application, you must export the application again and re-install it.


Installing COM+ Server Applications

You can use the Component Services administrative tool to install COM+ server applications.

To perform this procedure, you need to be a member of the Administrator role on the target computer's system application. In the default configuration, only local computer administrators are assigned to this role. For more information, see Setting Security.

The minimum configuration for an application is one in which security is not required. If security is required for the application, use the Component Services administrative tool to set process-level security or add users to predefined roles after the application has been installed. See Security Administration Tasks for more information on how to configure security for your application.

You can install COM+ server applications using the Component Services administrative tool, from the Windows Explorer, or from the command prompt.

Important You can install a COM+ server application only on Windows 2000 computers. A server application requires a platform that supports Component Services.

To install a COM+ server application with the Component Services administrative tool
  1. In the console tree of the Component Services administrative tool, double-click the computer to which you want to install the application.
  2. Right-click the COM+ Applications folder for that computer, point to New, and then click Application.
  3. In the initial dialog box for the COM Application Install Wizard, click Next.
  4. In the Install or Create a New Application dialog box, click Install pre-built application(s).
  5. In the Install from application file dialog box, browse to select the .msi file for the application you are installing, and then click Open.
  6. In the Select Application Files dialog box, click Add to browse for any additional applications you want to install.
  7. Click Next.
  8. In the Set Application Identity dialog box, specify the application identity and then click Next.

    The default selection is Interactive User. The interactive user is the user who is logged on to the Windows 2000 account for the computer that runs an application. You can select a different user by clicking This user and entering details for a specific Windows 2000 user or group.

  9. In the Application Installation Options dialog box, specify the directory in which to install the COM+ application.

    The application's component files are copied from the .msi file to the installation directory. The default installation directory is:

    %Program Files%\COMPlus Applications\[<appid>]

    You can accept the default directory, or click Specific directory and Browse to search for another location.

    To perform this procedure, the application identity specified in step 9 must have at least read access to the installation directory; and, the person running the Component Services administrative tool during this process must have write access to the installation directory.

  10. Click Finish.

    The hierarchy in the Explorer console tree now shows the new application in the detail pane. If you install multiple applications, the options you choose in steps 9 and 10 apply to all the applications.

To install a COM+ server application from the Windows Explorer
  1. On the computer to which you want to install the COM+ application, locate the server application file (.msi) using the Windows Explorer. The file can reside locally or on a network share.
  2. Double-click the server application file. You can also right-click the file name and then click Install. The Microsoft installer automatically installs the server application on the target computer.

To install a COM+ server application from the command prompt
  • At the command prompt, type the following:

    msiexec -i [<property overrides>] <application_name>.msi

    In addition to the standard Windows Installer property overrides, you can specify the following option to change the installation directory for the COM+ application from the default to the specified directory:

    TARGETDIR = <target installation directory>

Alternatives to This Procedure

You can also install a COM+ application by dragging an application file from the Windows Explorer to the details pane of the Component Services administrative tool while the COM+ Applications folder of a computer is open.


Exporting COM+ Application Proxies

You can use the Component Services administrative tool to export a COM+ application proxy. Once the proxy is installed on client computers, client applications will be able to use the proxy information to find and access, via DCOM, a COM+ server application running on a production computer.

To export a COM+ application proxy
  1. In the Component Services administrative tool console tree, right-click the application, and then click Export.
  2. In the initial dialog box for the COM+ Application Export Wizard, click Next.
  3. In the Application Export Information dialog box, enter the full path of the application proxy file to be created, or click Browse to search for an existing file or directory.
  4. Under Export as, click Application proxy - Install on other machines to enable access to this machine.
  5. Click Next.
  6. In the closing dialog box, click Finish.

By default, the application proxy file includes remote server information that points to the server computer from which the application proxy was exported. If you export an application proxy from a virtual server when using the Cluster service, by default the application proxy will use the node the virtual server was on when exporting as the remote server name. You can change the default remote server name using the Component Services administrative tool.

To specify an alternate remote server used by application proxies
  1. In the Component Services administrative tool console tree, right-click the computer from which you are exporting applications.
  2. In the computer properties dialog box, click the Options tab.
  3. Under Export, in the Application proxy RSN box, enter the name of the remote server computer to be used by application proxies.
  4. Click OK.

Note that the default remote server name in an application proxy file can also be overridden at installation time. See Installing COM+ Application Proxies for more information.

Important If a component's class ID (CLSID), type library identifier (TypeLibId), or interface identifier (IID) change after you have exported an application, you must export the application proxy again and re-install it on the client computers.


Installing COM+ Application Proxies

Once the application proxy is created as a Windows Installer (.msi) file, it is a simple task to install it on a client computer. Installing the application proxy provides the registration information needed for client applications to access the COM+ application remotely from the client computer.

Important You can install a COM+ application proxy on any computer that's running the Windows Installer. The Windows Installer is automatically installed on all Windows 2000 computers and is available for Windows 95, Windows 98, and Windows NT 4.0 computers. However, if an application proxy requires the queued components service, this proxy can only be installed on a Windows 2000 computer. The queued components service is only available on platforms that support Component Services.

To install a COM+ application proxy from the Windows Explorer
  1. On the client computer, locate the application proxy file (.msi) using the Windows Explorer. This file can reside locally or on a network share.
  2. Double-click the application proxy file. You can also right-click the file name and then click Install. The Microsoft installer automatically installs the application proxy on the client computer.

To install a COM+ application proxy from the command prompt
  • At the command prompt, type the following:

    msiexec -i [<property overrides>] <application_name>.msi

    In addition to the standard Windows Installer property overrides, you can specify the following options:

Installer Option | Description
REMOTESERVERNAME = <new target server> | Changes the server to which the client computer will connect from the exported default to the specified new target server.
ALLUSERS = 0 | Installs the application proxy only for the current user. By default, the application proxy is installed machine-wide.
TARGETDIR = <target installation directory> | Changes the installation directory for the COM+ application from the default to the specified directory.


Removing COM+ Applications

As existing applications become outdated or are no longer being used, you may need to remove them.

To delete a COM+ application
  1. In the console tree of the Component Services administrative tool, double-click the computer for which you want to delete an application.
  2. Double-click the COM+ Applications folder for the specified computer to display all the applications.
  3. Click the application you want to remove.
  4. If you selected a server application, shut down the application. To do this, right-click the application, and then click Shut down. If you selected a library application, make sure that all processes currently using this library application are shut down.
  5. Right-click the application, and then click Delete.
  6. Click Yes to remove the application.

Note If you delete a COM+ server application while it is running, the application will be shut down without warning prior to being deleted.

Alternatives to This Procedure

There are several other ways you can remove server applications and application proxies, as follows:

  • Use the Add/Remove Programs control panel.
  • Right-click the .msi file, and then click Uninstall.
  • Delete a COM+ application using the following Windows Installer command prompt syntax:

    msiexec -x <application_name>.msi

These methods are especially useful for deleting COM+ applications on client computers that are not running the Component Services administrative tool.

Deleting the application also deletes any components contained in the application. If these components depend on additional resources (database connections, data or text files, IIS virtual root configuration, and so on), these resources must be removed through mechanisms other than the Component Services administrative tool.


Replicating COM+ Applications

You may need to replicate all COM+ applications and their configurations from one computer (master) to another computer (replication target). Replication is useful for the following scenarios:

  • Web farm
  • Fail-over cluster
  • Staging to production

You might replicate applications manually by repeatedly using the exporting and installing each of the applications on the master computer. However, you may find that it is simpler to perform this rather tedious and error-prone task with a replication utility (COMRepl.exe) for COM+ applications provided by Windows 2000. This replication utility copies all the COM+ applications from a master computer to a target computer. It also replicates all computer-wide COM+ configurations.

COMREPL is a command line utility invoked as follows:

COMREPL <sourceComputer> <targetComputerList> [/n [/v]]

The list of parameters is described in the following table:

Parameter | Description
<sourceComputer> | Computer name of the source.
<targetComputerList> | Computer names of the targets separated by spaces.
/n | Suppress confirmation prompt before starting replication.
/v | Echo log file output to the console.

Notes

  • All target computers must already have Component Services installed since only configuration data and applications are replicated, not Component Services.
  • The user must pass role checks for the system application on both the source and the target computers.
  • No local machine accounts that may be used by roles are replicated.
  • The target computer(s) must be online.
  • The user is responsible for replicating all data that is not related to Component Services (for example, database tables, data files, and so on) to the target computers.
  • Clusters of computers running Windows 2000 can participate in replication but since COMREPL only replicates to named computers, if a failed computer is replaced by a backup, the then named computer would be the one being replicated to.


Administering Application Security

Component Services provides a simple, robust security model that you can use to protect COM+ applications, data, and resources from accidental or malicious corruption. The central mechanism is that of roles: user categories that have been defined for an application by its developer. Roles are initially assigned to the application and its components by the developer, and then populated with actual users by the system administrator. Once in place, roles serve to enforce an access control policy for the application.

For administrative purposes, role-based security clarifies and simplifies security maintenance for a COM+ application. Tasks for administration of role-based security are typically as simple as populating an application's predefined roles with Windows 2000 groups or user accounts, and setting an identity for the application (a user account under which the application runs).

Use the following links to get background and task information.

Topic | Description
Security Administration Concepts | Provides an overview and links to more information on administering application security.
Security Administration Tasks | Provides links to step-by-step procedures on security-related tasks.

Before You Go On

Security should be an intrinsic part of an application's design. Developers assess security requirements and balance them against performance and functional requirements. The developer decides what level of role-based security is appropriate, and incorporates roles that represent the categories of users for whom the application is intended. These choices can impact every functional aspect of an application, so they should be made in the context of its overall design.

For a broad introduction to role-based security, see the COM+ Security section under Component Services in the Microsoft Platform SDK.

For a discussion of COM security, see the COM Security section under Component Services in the Microsoft Platform SDK.


Security Administration Concepts

The role-based security model used by COM+ applications is built on top of the security mechanisms of Windows 2000 and COM, including user identification, authentication services, and impersonation/delegation; these continue to function transparently in underlying layers. Windows 2000 provides basic protection by user identification through logons, controlled access to system resources and audited security events through Local Users and Groups, and file protection through the NTFS file system. You should be familiar with Windows 2000 security features when administering Component Services security. For more information, consult the Windows 2000 documentation and the Microsoft Windows 2000 Resource Kit for background information.

Administration of COM+ Application Security

Where security for COM+ applications is concerned, administrative tasks include:

  • Assign Windows 2000 user groups to predefined roles for the application, then manage those roles on an ongoing basis.
  • Set the application identity on installation, generally to a user account, which the application runs under and uses when it makes calls out to other applications and resources. (This only applies to server applications; it is not required for library applications.)

Administering role-based security effectively requires knowledge of the application's security needs and how they are enforced through roles. It is crucial that users are assigned to the roles appropriate to them according to the application's security policy. For background see the following topics.

Topic | Description
Role-Based Security | Offers an overview of how role-based security works, along with links to related tasks.
Application Identity | Provides an overview of how the application identity is used, along with links to related information.

Caution Using the Component Services administrative tool, you can change the role-based security settings that a COM+ application uses. It is strongly recommended that you do not modify an application's security settings. An application that uses role-based security may contain code that relies on checking role membership. If you modify its security settings, an application might not run at all, it might not run as intended, or it might run unsecured.

Administration of COM Application Security

COM applications use a number of security configuration properties. These properties have machine-wide settings that an application can use by default. Alternatively, COM security configuration can be customized for any particular application. If an application does not have custom security settings, it will use the settings set for the machine on which it resides.

You can change the COM machine-wide security properties using the Component Services administrative tool, and you can set customized security properties for a particular COM application using the DCOMCNFG utility. In general, it is not necessary that you change anything, though for particular applications or particular systems, security requirements may dictate that you do so.

Topic | Description
COM Security Settings | Provides an overview of the COM security configuration properties, along with links to related information.

For a description of what distinguishes COM applications from COM+ applications, see Component Services Administration Concepts. For a full discussion of COM security, together with procedures for using DCOMCNFG, see the COM Security section under Component Services in the Microsoft Platform SDK.


Role-Based Security

Security roles model and enforce an access control policy for a COM+ application. Roles are categories of users that have been defined for the application for the purpose of determining access permissions to the application's resources. The developer assigns the roles (as symbolic user categories) to the application and potentially to finer structures within it — including components, interfaces, methods, or private application resources. These role assignments are then used to determine which user categories have permission to access which elements within the application. When an application uses role-based security, a caller's role membership is checked on every call into the application. If a caller does not belong to a role having permission to access the item being called, the call will fail. Callers are granted access to the application or its resources strictly according to the constraints defined within the roles to which they belong.

The system administrator's job is to populate the roles defined for the application with Windows 2000 user accounts and groups. This is a crucial stage in carrying out the application's security policy. Users must be assigned to the roles that correctly represent their relationship to the data and resources they might access through the application.

Assigning Groups of Users

The preferred way to populate roles with users is to use Windows 2000 groups. First you assign a user account to the appropriate groups, and then ensure that the groups are assigned to the appropriate roles. Using Windows 2000 groups to populate roles makes it easier for you to manage large numbers of users. In enterprise computing environments, it is often difficult to effectively track each user's place within the organization and determine how that maps into the role-based security policy particular to each application. As the number of users, administrators, and applications rises, this task becomes increasingly complicated. The most scalable solution is to assign user groups to COM+ application roles.

Before you assign any groups to roles, you need to be sure that you understand the application's security policy. Ideally, roles should carry names that suggest who should belong to them, such as "Managers" and "Tellers." In addition, there are descriptions for each role that you can access using the Component Services administrative tool that may describe what kinds of users should belong to the role. However, if you are not sure which user groups belong in which roles, consult the documentation that accompanies the application or ask the developer for clarification.

You can use the Component Services administrative tool both to make the initial assignments to roles during application installation and to make any necessary changes in role membership during the application's lifetime.

See the following topics for step-by-step instructions on tasks that are part of managing role membership.

  • Assigning a User Account or Group to a Role
  • Removing a User Account or Group from a Role
  • Moving a User Account or Group to a Different Role


Application Identity

The application identity is the user account under which the application runs. When you install a COM+ server application — that is, a COM+ application running in its own process space — you need to set the identity for it. The identity can be set to either Interactive User, meaning whatever user is logged on to the computer running the application, or it can be set to a particular user account along with a valid password. You do not need to set the identity for COM+ library applications, which run in the client's process space under the client's identity.

The identity determines the security context for calls that the application makes when it runs. When the application makes calls to other applications, it does so using its identity (provided it is not impersonating a client when making calls on the client's behalf). An application receiving the call uses the calling application's identity to do its own security checking to validate the call.

Interactive User Identity Versus a Specified User

Specifying a particular user is usually preferable to using the interactive user identity. When a particular user identity is used the server can run even when no one is logged on to the machine on which the application is running. A particular user identity is also more secure than interactive user because it can only be assigned to the application by someone who has the specific user's password.

If the identity is set to interactive user, the application will only run when a user is logged on. Interactive user is the only identity that allows the client to see a graphical user interface (GUI) provided by the application. Choosing interactive user identity, though, carries security risks, because the application runs under the identity of the logged on user without that user's knowledge or consent. For instance, if the application is running on a computer while an administrator is logged on, the application will run under the administrator's identity, potentially making calls as such on behalf of clients.

Requirements for Delegation to Work

Delegation is server impersonation of a client over the network; that is, the application, as a server, is making calls to other applications on remote machines using the client's identity with the client's permission. Since this is a very powerful level of authority to grant an application, with potential security risks, the behavior of delegation can be controlled administratively through the Active Directory directory service. When a client application is granting a server permission to do delegate-level impersonation, two requirements must be met for it to work:

  • The server application must be running under an identity which is marked as "Trusted for delegation" in Active Directory.
  • The client application must be running under an identity which is not marked as "Account is sensitive and cannot be delegated" in Active Directory.

When setting the identity for a COM+ application that you want to be able to perform delegation on behalf of clients, if you set it for a particular user identity that user must be a domain user account which is trusted for delegation. If interactive user identity is used, then whatever user is logged on must be trusted for delegation. If the application identity is not trusted for delegation, then when the application attempts to impersonate a client over the network the call will fail. For a description of impersonation levels, see Impersonation Level.

For step-by-step instructions on setting identity, see Setting Application Identity.


COM Security Settings

COM applications — Microsoft Word, for example, is a COM application — use a number of security configuration properties: authentication level, impersonation level, access permissions, launch permissions, and configuration permissions. These properties have machine-wide settings that an application can use by default. Alternatively, COM security properties can be configured specifically for any particular application. If an application does not have specified security settings, it will use the machine-wide settings.

In general, it is not necessary that you change anything, though for particular applications or particular systems, security requirements may dictate that you do so. You can change the COM machine-wide security settings using the Component Services administrative tool, as described in this topic. You can set the security properties for a particular COM application using the DCOMCNFG utility.

For detailed descriptions of the procedures to follow using DCOMCNFG, see "Setting Process-Wide Security Using DCOMCNFG" in the "COM Security" section under "Component Services" in the Microsoft Platform SDK.

For a description of what distinguishes COM applications from COM+ applications, see Component Services Administration Concepts.

Machine-Wide Security Settings

The machine-wide COM security settings do not apply to COM+ applications; they apply only to COM applications. For each COM security property, a COM application can either use the machine-wide setting or use a custom setting. Whenever an application has custom security settings the machine-wide settings are disregarded, but an application that does not have its own settings will use the machine-wide settings.

You can modify the machine-wide security settings using the Component Services administrative tool if the default values do not meet the security requirements of the applications on your system. Keep in mind that changing the machine-wide settings will affect every COM application that does not have custom configuration.

If you want to use the default machine-wide settings, you do not have to do anything. COM will use the following default values automatically for the machine-wide security settings:

  • An authentication level of Connect.
  • An impersonation level of Identify.
  • Access permissions granting permissions to the server identity and the local system.
  • A principal name based on the user name and password.
  • A security service provider determined by COM to be the best for the environment. In Windows 2000, this will be Kerberos or NTLMSSP.

Use the following links to get background and task information.

Topic | Description
Authentication Level | Provides an overview of levels at which client and server verify one another's identity using credentials, and by which they verify and encrypt data that passes between them.
Impersonation Level | Introduces levels through which a server makes a call on behalf of a client, and presents the client's identity and credentials in place of its own when making the call.
Access Permissions | Introduces permissions specifying a list of users who are granted or denied access to COM applications.
Launch Permissions | Provides an overview of permissions that specify a list of users who are granted or denied permission to launch, or start, COM applications.
Reference Tracking | Introduces a technology through which COM will do additional security checks to authenticate reference count calls and will track additional information to prevent objects from being accidentally or maliciously released too early.


Authentication Level

Authentication is the process by which client and server verify one another's identity using credentials, and by which they verify and encrypt data that passes between them.

The authentication level setting indicates what degree of authentication is required for communication with an application (when it makes or receives calls). Higher authentication levels provide greater security and data integrity, though usually with some performance degradation. You should use caution in changing the authentication level: COM will negotiate the authentication level between client and server to be the maximum specified by either. However, this negotiation can fail if the client specifies the authentication level programmatically to a lower level than that required by the server. If you change the authentication level it can potentially cause some calls to fail (for example, if you raise the server authentication to a level above that specified programmatically by a client). Such failures are often difficult to diagnose and to predict.

Using the Component Services administrative tool, you can change the machine-wide setting for the authentication level. This machine-wide setting is used when a COM application doesn't specify an authentication level programmatically. This setting does not affect COM+ applications. The default setting for machine-wide authentication level is Connect.

The levels, from lowest to highest security, are as follows:

Level | Description
None | No authentication occurs.
Connect | Authenticates credentials only when the connection is made.
Call | Authenticates credentials at the beginning of every call.
Packet | Authenticates credentials and verifies that all call data is received.
Packet Integrity | Authenticates credentials and verifies that no call data has been modified in transit.
Packet Privacy | Authenticates credentials and encrypts the packet, including the data and the sender's identity and signature.

For step-by-step instructions on setting levels, see Setting the Machine-Wide Authentication Level.


Impersonation Level

Impersonation is the process by which a server makes a call on behalf of a client, and presents the client's identity and credentials in place of its own when making the call. This can take place only when the client explicitly grants the server permission to use its identity.

The impersonation level setting is used by the client to grant the server a particular level of authority to carry out actions on its behalf. The highest level of trust is required for the server to be able to impersonate the client over the network. Local impersonation is impersonate-level impersonation; impersonation over the network is delegate-level impersonation, or delegation. For the server to be able to perform delegation, it must be running under an identity that is marked as "Trusted for delegation" in Active Directory. For the client to be able to grant delegate-level authority, it must not be marked as "Account is sensitive and cannot be delegated" in Active Directory. (See Application Identity for more information on identities and delegation.)

Using the Component Services administrative tool, you can change the machine-wide setting for the impersonation level. This machine-wide setting is used when a COM client on the machine doesn't specify an impersonation level programmatically. This setting does not affect COM+ applications. The default setting for machine-wide impersonation level is Identify.

The levels, from granting least to greatest authority, are as follows:

Level | Description
Anonymous | The client is anonymous to the server. The server can impersonate the client, but the impersonation token (a local credential) does not contain any information about the client.
Identify | The server can obtain the client's identity, and can impersonate the client to do ACL checks.
Impersonate | The server can impersonate the client while acting on its behalf, though with restrictions. The server can access resources on the same computer as the client. If the server is on the same computer as the client, it can access network resources as the client. If the server is a computer different from the client, it can only access resources that are on the same computer as the server.
Delegate | The server can impersonate the client while acting on its behalf, whether or not on the same computer as the client. During impersonation, the client's credentials (both those with local and with network validity) can be passed to any number of machines.

For step-by-step instructions, see Setting the Machine-Wide Impersonation Level.


Access Permissions

Access permissions specify a list of users who are granted or denied access to COM applications. The machine-wide access permissions apply to all COM applications that do not specify their own access permissions.

Using the Component Services administrative tool, you can add or remove user accounts or groups to the list of users having access permissions. This does not affect COM+ applications.

When setting access permissions, you must ensure that SYSTEM is included in the list of users that are granted access. If you have granted access permissions to Everyone, SYSTEM is included implicitly.

For step-by-step instructions, see Setting Machine-Wide Access Permissions.


Launch Permissions

Launch permissions specify a list of users who are granted or denied permission to launch, or start, COM applications. The machine-wide launch permissions apply to all COM applications that do not specify their own launch permissions.

Using the Component Services administrative tool, you can add or remove user accounts or groups to the list of users having machine-wide launch permissions. This does not affect COM+ applications.

For step-by-step instructions, see Setting Machine-Wide Launch Permissions.


Reference Tracking

When you enable reference tracking, also known as "secure reference counting," COM will do additional security checks to authenticate reference count calls and will track additional information to prevent objects from being accidentally or maliciously released too early. Enabling reference tracking increases system security but can decrease performance.

For step-by-step instructions, see Setting Machine-Wide Reference Tracking.


Security Administration Tasks

The security administration tasks that you can accomplish with the Component Services administrative tool are:

  • Managing Users in Roles
  • Setting Application Identity
  • Setting Machine-Wide COM Security Configuration

For overview information on these tasks, see Security Administration Concepts.


Managing Users in Roles

Most administration tasks for configuring COM+ application security involve populating predefined roles with users, both when installing applications and on an ongoing basis. For introductory information on how these security features work see Role-Based Security.

Step-by-step instructions are provided in this section for the following tasks:

  • Assigning a User Account or Group to a Role
  • Removing a User Account or Group from a Role
  • Moving a User Account or Group to a Different Role


Assigning a User Account or Group to a Role

You can use the Component Services administrative tool to populate a role with user accounts or groups. The preferred way to assign a user account to a role is to assign the user account to a Windows 2000 group and then assign the group to the role. Using Windows 2000 groups to populate roles makes it easier for you to manage large numbers of users.

For more information on creating a Windows 2000 group or assigning a user account to an Windows 2000 group, see the online help available from Local Users and Groups in Computer Management. After you have assigned the user account to the appropriate Windows 2000 group, follow the steps below to assign the Windows 2000 group to the role.

To assign a Windows 2000 group to a security role
  1. In the console tree of the Component Services administrative tool, locate the COM+ application that contains the role to which you want to add the user account or group. Expand the view in the console tree until the application's roles are visible.
  2. Locate the role to which you want to add the user account or group.

    Note If the role you are looking for is not in the Roles folder, the role has not been added to the application. It must be added to the application by the developer before you can assign user accounts to the role.

  3. Right-click the Users folder for the role, point to New, and then click User.
  4. In the Select Users or Groups box, in the bottom pane, type the fully qualified name of the group you want to add.

    If you do not know the name, select the domain in the Look in box, select the group from the Names list, and then click Add.

  5. To add more user accounts or groups, repeat step 4.
  6. When you have finished adding user accounts and groups to the role, click OK.

For each user account or group you have assigned to the role, an icon will appear in the Users folder. The new role membership will take effect the next time the application is started.


Removing a User Account or Group from a Role

You may need to remove user accounts or groups from a role when the users or members of the groups should no longer be given access to the application resources to which the role is assigned.

To remove a user account or group from a role
  1. In the console tree of the Component Services administrative tool, locate the COM+ application that contains the role you are interested in. Expand the view in the console tree until the users for the role are visible.
  2. Right-click the user account or group you want to remove, and then click Delete.
  3. When prompted by the Confirm Item Delete dialog box, click Yes to delete the user account or group.

The user account or group that you have removed from the role will no longer appear in the Users folder. The new role membership will take effect the next time the application is started.


Moving a User Account or Group to a Different Role

If a user's privileges change or if roles are added to an application, you may need to move an account from one role to another role. In order to move a user account or group of users from one role to another, you must remove the user account or group from its current role and then assign it to the new role.

To move a user account or group from one role to another
  1. Remove the user account or group from the role that it should no longer belong to. To do this, follow the procedure described in Removing a User Account or Group from a Role.
  2. Assign the user account or group you have removed to the roles that the user or group should be assigned to. For help with this task, see Assigning a User Account or Group to a Role.

The icon representing the user account or group you have moved will appear in the Users folder for the role you have assigned it to. The new role membership will be effective the next time the application is started.


Setting Application Identity

Using the Component Services administrative tool, you can set the identity for a COM+ server application. (For a COM+ library application, the identity is always the identity of the hosting process.) The identity can be set to either a particular user account, along with a valid password, or to "Interactive user." The application runs under this user account, and uses it when it makes calls to other applications or resources. For an overview of application identities, see Application Identity.

To set the identity for a COM+ server application
  1. In the console tree of the Component Services administrative tool, right-click the COM+ application whose identity you want to set, and then click Properties.
  2. In the properties dialog box, click the Identity tab.
  3. Under Account, select from the following options:
    • To specify that the server will run under the identity of the logged on user, click Interactive user.
    • To specify that the server will run under a particular user's identity, click This user, and then enter the user name, password, and confirmed password.

    Or, if you don't know the fully qualified user name, click Browse to locate it. When you have located the user name in the Browse for Users dialog box, click OK.

  4. Click OK.

The identity you selected will take effect the next time the application is started.


Setting Machine-Wide COM Security Configuration

Using the Component Services administrative tool you can set the machine-wide COM security properties that are used by COM applications. For more information on how these security features work see COM Security Settings.

Step-by-step instructions are provided in this section for the following tasks:

  • Setting the Machine-Wide Authentication Level
  • Setting the Machine-Wide Impersonation Level
  • Setting Machine-Wide Access Permissions
  • Setting Machine-Wide Launch Permissions
  • Setting Machine-Wide Reference Tracking


Setting the Machine-Wide Authentication Level

The authentication level tells COM the extent to which clients and servers should verify one another's identity during calls between applications. If you want to enable security for a computer, you must choose a machine-wide authentication level other than None. For overview information, see Authentication Level.

To set the machine-wide authentication level
  1. In the console tree of the Component Services administrative tool, right-click the computer whose machine-wide authentication level you want to modify, and then click Properties.
  2. On the Default Properties tab, in the Default Authentication Level box, select a value other than (None).
  3. Click OK.

The new machine-wide authentication level will be available the next time an application on the computer is started. Applications that are currently running will not be affected until they are restarted.


Setting the Machine-Wide Impersonation Level

The impersonation level, set by the client, determines the amount of authority given to the server to act on the client's behalf. Setting the machine-wide impersonation level for the whole computer tells COM what impersonation level to use when a particular client on the machine doesn't specify an impersonation level programmatically. For overview information, see Impersonation Level.

To set the machine-wide impersonation level
  1. In the console tree of the Component Services administrative tool, right-click the computer whose machine-wide impersonation level you want to modify, and then click Properties.
  2. On the Default Properties tab, in the Default Impersonation Level box, select the impersonation level you want.
  3. Click OK.

The new machine-wide impersonation level will be available the next time an application on the computer is started. Applications that are currently running will not be affected until they are restarted.


Setting Machine-Wide Access Permissions

Machine-wide access permissions specify a list of users who are granted or denied access to COM applications that do not provide their own access permissions. When setting access permissions, you must ensure that SYSTEM is included in the list of users that are granted access. If you have granted access permissions to Everyone, SYSTEM is included implicitly. For overview information, see Access Permissions.

To set machine-wide access permissions
  1. In the console tree of the Component Services administrative tool, right-click the computer whose machine-wide access permissions you want to modify, and then click Properties.
  2. On the Default Security tab, under Default Access Permissions, click Edit Default.
  3. To remove a user account or group, in the Registry Value Permissions dialog box select the user account or group you want to remove and then click Remove.

    The selected user account or group will no longer appear in the list. When you have finished removing user accounts and groups, click OK.

  4. To add a user account or group, click Add.
  5. In the Add Users and Groups dialog box, type the fully qualified user name in the Add Names box.

    Or, if you don't know the user name, you can browse the user database to find it.

  6. From the Type of Access list, select the access type (either Allow DefaultAccessPermission or Deny DefaultAccessPermission).

    To add other user accounts that will have the selected type of access, repeat step 5.

  7. When you have finished adding user accounts for the selected access type, click OK.
  8. To add user accounts that will have a different type of access, repeat steps 5 through 7.
  9. Click OK.

The new machine-wide access permissions will be available the next time an application on the computer is started. Applications that are currently running will not be affected until they are restarted.


Setting Machine-Wide Launch Permissions

The machine-wide launch permissions you set with the Component Services administrative tool determine a list of users, each of which is explicitly granted or denied permission to launch COM applications that do not provide their own launch permission settings. When setting launch permissions, you can add or remove one or more user accounts or groups from this list. For overview information, see Launch Permissions.

To set machine-wide launch permissions
  1. In the console tree of the Component Services administrative tool, right-click the computer whose machine-wide launch permissions you want to modify, and then click Properties.
  2. On the Default Security tab, under Default Launch Permissions, click Edit Default.
  3. To remove a user account or group, in the Registry Value Permissions dialog box select the user account or group you want to remove and then click Remove.

    The selected user account or group will no longer appear in the list. When you have finished removing user accounts and groups, click OK.

  4. To add a user account or group, click Add.
  5. In the Add Users and Groups dialog box, type the fully qualified user name in the Add Names box.

    Or, if you don't know the user name, you can browse the user database to find it. When you have located the user name, select the user account or group from the Names list and then click Add.

  6. From the Type of Access list, select the access type (either Allow DefaultLaunchPermission or Deny DefaultLaunchPermission).

    To add other user accounts that will have the selected type of access, repeat step 5.

  7. When you have finished adding user accounts for the selected access type, click OK.
  8. To add user accounts that will have a different type of access, repeat steps 5 through 7.
  9. Click OK.

The new machine-wide launch permissions will be available the next time an application on the computer is started. Applications that are currently running will be not affected until they are restarted.


Setting Machine-Wide Reference Tracking

When you enable reference tracking, you are asking COM to do additional security checks and keep track of additional information to keep objects from being accidentally or maliciously released too early. Enabling reference tracking, which is also known as secure reference counting, can also decrease performance. For an overview of reference tracking, see Reference Tracking.

To enable (or disable) reference tracking for a computer
  1. In the console tree of the Component Services administrative tool, right-click the computer for which you want to set reference tracking, and then click Properties.
  2. On the Default Properties tab, under Default Distributed COM communication properties, select from the following options:
    • To enable reference tracking, select the Provide additional security for reference tracking check box.
    • To disable reference tracking, clear the Provide additional security for reference tracking check box.
  3. Click OK.

The new reference tracking setting will be available the next time an application on the computer is started. Applications that are currently running will not be affected until they are restarted.


Administering Distributed Transactions

In applications developed to use distributed transactions, concurrent work done by multiple clients, components, and databases can be managed to help protect the application against failures. Within a transaction, either all the work done by participating components happens or none of it does, simplifying tracking and error recovery because no loose ends are left by failures.

With the Component Services administrative tool, which includes the Microsoft Distributed Transaction Coordinator (MS DTC), you can configure your computers and network to support distributed transactions, as well as monitor and manage distributed transactions.

Note You can use MS DTC with Windows 95, Windows 98, Windows NT 4.0, Windows 2000, and later.

Use the following links to get background and task information.

Topic | Description
Distributed Transaction Administration Concepts | Provides an introduction to MS DTC, along with links to more information.
Distributed Transaction Administration Tasks | Provides links to distributed transaction administration tasks.

Before You Go On

Decisions about transaction attributes, such as when a transactional component requires or supports a transaction, are typically made as the component or application is developed. Administrative decisions, on the other hand, are generally focused on configuring, starting and stopping MS DTC, monitoring and managing the flow of transactions, and monitoring transaction performance.


Distributed Transaction Administration Concepts

You can administer distributed transactions through the Microsoft Distributed Transaction Coordinator (MS DTC), included in the Component Services administrative tool. MS DTC provides transaction services to ensure successful and complete transactions, even with system failures, process failures, and communication failures.

What is the Microsoft Distributed Transaction Coordinator?

The MS DTC is the distributed transaction facility for Windows 95, Windows 98, Windows NT, Windows 2000 , and later. MS DTC coordinates transactions that update two or more transaction-protected resources such as databases, message queues, file systems, and so on. These transaction-protected resources may be contained on a single system or distributed across a network of systems. For example, MS DTC permits an application to update a Microsoft SQL Server database on one Windows 2000 system, a Microsoft Message Queue Server message queue on a Windows NT system, an Oracle database on a UNIX system, and a DB2 database on an MVS system, all under the control of a single distributed transaction.

MS DTC uses proven transaction processing technology. It is robust despite system failures, process failures, and communication failures. It exploits loosely coupled systems to provide scalable performance. It is easy to install, configure, and manage.

MS DTC provides the following benefits:

  • It lowers the cost of enterprise computing — MS DTC provides a sophisticated, cost-effective distributed transaction facility for users of networked commodity-priced PCs and servers.
  • It simplifies application development — MS DTC transactions greatly simplify the application programmer's task of preserving consistency, despite failures that can occur when updating distributed application data.
  • It provides a consistent transaction model for updating a wide variety of data sources, including relational databases, message queues, file systems, and document storage systems.
  • It enables software development using distributed, object-oriented software components. MS DTC is based on the OLE Transactions interface standard, which provides a simple, object-oriented application programming interface for initiating and controlling transactions.

Use the following links to get background information for performing administration tasks.

Topic | Description
Transactions Overview | Provides an introduction to transactions, distributed transactions, and the role of MS DTC.
Distributed Transactions Overview | Provides a detailed overview of distributed transactions, along with links to topics on optimizations supported by MS DTC.
Components of MS DTC | Introduces MS DTC components and describes how to configure them within your network.
MS DTC Configuration | Introduces options for configuring MS DTC for your particular network needs.
Log File Management | Provides an overview of streamlining performance by managing the transaction log file.
Transaction State Resolution | Provides an overview of transaction resolution after a system failure, along with links to more specific information.


Transactions Overview

In a transaction, each participating component must agree to commit a change action (such as a database update) before the transaction can occur. MS DTC performs the transaction coordination role for the components involved, and acts as a transaction manager for each computer that manages transactions.

In the two-phase commit algorithm for MS DTC, phase one involves the transaction manager requesting each enlisted component to prepare to commit; in phase two, if all successfully prepare, the transaction manager broadcasts the commit decision.

In general, transactions involve the following steps:

  1. Applications call the transaction manager to begin a transaction.
  2. When the application has prepared its changes, it asks the transaction manager to commit the transaction. The transaction manager keeps a sequential transaction log so that its commit or abort decisions will be durable.
    • If all components are prepared, the transaction manager commits the transaction and the log is cleared.
    • If any component cannot prepare, the transaction manager broadcasts an abort decision to everyone involved in the transaction.
    • While a component remains prepared but not committed or aborted, it is in doubt about whether the transaction committed or aborted. If a component or transaction manager fails, it reconciles in-doubt transactions when it reconnects.

For information describing how transactions provide atomicity, consistency, isolation, and durability, refer to Transactions and the ACID Properties.

For information describing transactions and the commit process, refer to Transaction Participants and Two-Phase Commit.


Transactions and the ACID Properties

Transactions provide atomicity, consistency, isolation, and durability. These are referred to as the ACID properties. The following table describes each.

Property | Description
Atomicity | Atomicity is the "all or nothing" property of transactions. A transaction will either commit or abort. If a transaction commits, all of its effects remain; if it aborts, all of its effects are undone.
Consistency | A transaction always transforms the state of the system from one consistent state to another. As a result, any single transaction (or any sequence of transactions) always leaves the system in a consistent state.
Isolation | If two transactions are executing concurrently, the changes made by one transaction are isolated from the other. Although two or more transactions may actually run in parallel, the system provides the illusion that the transactions ran one at a time. This prevents one transaction from being effected by the uncommitted updates being made by another transaction. This property is sometimes called serializability.
Durability | Once a transaction commits, its effects will persist even if there are system failures.


Transaction Participants and Two-Phase Commit

Transactions normally involve a transactional application, a transaction manager, and one or more transactional resource managers.

Transactional Application

Transactional application programs initiate transactions and specify whether they wish the transaction to commit, update, or abort. The application programmer's model is simple: transactions either succeed or fail. An application initiates a new transaction by calling the transaction manager's BeginTransaction method and obtaining a transaction object. All subsequent application work is associated with that transaction object. When the application reaches a consistent state, it calls the transaction manager's Commit method. If the commit succeeds, the transaction is durably committed. The transaction manager and the resource managers ensure that the transaction's effects are durable, even if there are subsequent failures.

MS DTC also permits applications or other entities the ability to learn that a transaction is ready to enter the "prepare" state of the two-phase commit (2PC) protocol before the prepare is sent. This feature is called Phase Zero notifications. If the application is not capable of providing the durability guarantees required by transaction (for example, acting as a full resource manager and participating in 2PC and recovery), then it must ensure that it has flushed all modified data to a full-service resource manager before the 2PC protocol is initiated. Phase Zero notifications provide a mechanism by which applications can detect that a transaction is ready to proceed with 2PC, so that they can perform such operations and communicate to the Transaction Manager when they have been completed. This support is available for new applications developed with the version of MS DTC which ships with Windows 2000.

If the application cannot successfully complete the transaction, it may call the transaction manager's Abort method. This will cause the transaction manager to abort the transaction and undo all of the transaction's effects. The transaction manager will also abort the transaction if the application fails before committing the transaction, a resource manager is unable to commit the transaction, or the computer fails. In all cases the transaction manager aborts the transaction and ensures that the transaction's effects are undone.

Transaction Manager

The MS DTC transaction manager coordinates transactions to ensure that they are atomic and durable. The transaction manager initiates a new transaction when an application calls the transaction manager's BeginTransaction method. When a resource manager first participates in a transaction, it calls the transaction manager's Enlist method to join in the transaction. The transaction manager tracks all the resource managers who enlist in the transaction.

When the application calls the Commit method, the transaction manager initiates the two-phase commit protocol. The purpose of the two-phase commit protocol is to guarantee that the transaction outcome is atomic — either all of the resource managers must agree to commit the transaction or they must all abort the transaction.

During the first phase, the transaction manager asks all enlisted resource managers to prepare to commit the transaction. The resource managers inform the transaction manager when they are prepared. Once all of the resource managers have prepared, the transaction manager makes the decision to commit the transaction and writes a commit record to its log file. The transaction manager then initiates the second phase of the two-phase commit protocol, during which it informs all the resource managers that the transaction has committed.

The transaction manager will abort the transaction if the application calls the Abort method, or any resource manager is unable to successfully prepare, or the application or system fails before the commit record is logged at the completion of phase one.

The MS DTC transaction manager maintains an MS DTC log file on its local system. The MS DTC log file captures all of the information that MS DTC must remember regarding the transaction. During normal processing, the transaction manager only writes to the log file. However, if the transaction manager fails, it reads the log file when it restarts to determine the state of recent transactions.

Transactional Resource Managers

Transactional resource managers are responsible for managing transaction-protected data. Typical transactional resource managers include SQL Server databases, message queuing systems, file systems, and document storage systems.

Transactional applications call the resource manager to insert, delete, or update application data. When a transactional application request arrives from the application that is associated with a new transaction, the resource manager invokes the transaction manager's Enlist method. By enlisting, the resource manager ensures that the transaction manager calls it when the transaction commits or aborts. After enlisting in the transaction, the resource manager performs the transactional application's request. For example, it might insert, delete, or update records in a relational database. The resource manager always retains enough information to enable it to either undo or redo the transaction. It may do this by storing multiple versions of the data or by keeping a log of the changes it makes to the data.

When the application calls commit, the transaction manager initiates the two-phase commit protocol by asking each resource manager to prepare. Typically the resource manager prepares by writing both the old and new data values to disk so that it can recover the data even if the system fails and the data in memory is lost. Once the resource manager is prepared, it informs the transaction manager that it is prepared, and it awaits the transaction manager's decision on whether to commit or abort the transaction. Once all of the resource managers inform the transaction manager that they are prepared, the transaction manager makes the decision to commit the transaction. The transaction manager then informs all the resource managers that the transaction has committed. The resource managers commit the transaction and release any locks they held on behalf of the transaction.

If any resource manager cannot successfully prepare, it unilaterally aborts the transaction, undoes the effects of the transaction, and informs the transaction manager of this. The transaction manager writes an abort record to its log file that indicates that the transaction has aborted. It then notifies all other enlisted resource managers that the transaction has aborted. Because MS DTC uses a Presumed Abort protocol, it writes nothing to the MS DTC log file for aborted transactions when it is the global commit coordinator.

Once prepared, a resource manager must wait until it gets a commit or abort decision from the transaction manager. The entire two-phase commit protocol typically completes within a fraction of a second. However, a system or communication failure may delay the commit or abort notification for minutes or even hours. During this period, the resource manager is said to be in-doubt about the outcome of the transaction because it does not know whether the transaction committed or aborted. While the resource manager is in-doubt, it holds the locks protecting the data modified by the transaction, isolating these changes from any other transactions. When the system is restored to service, the transaction manager informs the resource manager of the transaction's outcome. The resource manager then commits or aborts the transaction and releases the locked data.

The transaction manager guarantees that transactions are atomic and durable despite resource manager failures. When a resource manager fails, the transaction manager aborts all of the transactions in which the resource manager is enlisted, except for those transactions that were prepared or committed prior to the failure. When the resource manager restarts, it queries the transaction manager about the outcome of the in-doubt transactions in which it was enlisted. The transaction manager tells the resource manager the outcome of each in-doubt transaction and the resource manager commits or aborts these transactions accordingly.

See Distributed Transactions Overview for more information on how this process differs when transactions cross computer boundaries.


Distributed Transactions Overview

A distributed transaction updates data on two or more network connected computer systems. Implementing robust applications in a distributed environment is difficult because these applications are subject to many types of failures, including failures of the client, the servers, and the network. In the absence of distributed transactions, the application program itself must detect and recover from these failures. Distributed transactions eliminate this burden from the application developer.

MS DTC supports transactions that are distributed across two or more Windows 95, Windows 98, Windows NT, Windows 2000, and later systems. All applications and resource managers communicate with their local transaction manager. The local transaction manager cooperates with remote transaction managers to coordinate transactions that span systems, as illustrated by the following.

When a request containing a new transaction flows from one system to another, a relationship is established between the transaction managers on the two systems. The transaction manager on the originating system establishes an outgoing (or superior) relationship with the transaction manager on the destination system. Conversely, the transaction manager on the destination system establishes an incoming (or subordinate) relationship with the transaction manager on the originating system. These outgoing and incoming relationships form a tree of transaction manager relationships called the transaction commit tree.

Resource managers that enlist in the transaction are also members of this commit tree. The local transaction manager has an outgoing relationship with the resource managers enlisted with it. The resource managers have an incoming relationship with the transaction manager they are enlisted with.

Every transaction tree has exactly one root. The root of the commit tree is called the global commit coordinator. The global commit coordinator is the transaction manager that makes the decision to either commit or abort the transaction. For MS DTC, the global commit coordinator is the transaction manager on the system where the transaction originated.

The global commit coordinator commits or aborts a transaction by means of the two-phase commit protocol. It initiates the prepare, commit, and abort messages that flow outward on the commit tree. Any node of the tree can unilaterally abort a transaction any time before it agrees to the prepare request sent in the first phase. Once a node has prepared, it remains prepared and in doubt until the commit coordinator tells it to commit or abort the transaction. The global commit coordinator is never in doubt, because it makes the commit or abort decision.

If a computer fails and then restarts, the transaction manager at that computer tries to determine the outcome of all in-doubt transactions in which it participated. The transaction manager reads its log file to determine the outcomes of transactions for which it was the commit coordinator.

For incoming transactions from other systems, the transaction manager checks the log files to see if it was previously notified of the transaction outcome. For incoming transactions that remain in doubt, the transaction manager queries its superior transaction manager asking it about the transaction's outcome.

For outgoing transactions, the transaction manager contacts each subordinate transaction manager to which it sent the transaction and informs them of the transaction outcome. The transaction manager also responds to queries from its subordinate transaction managers regarding in doubt outgoing transactions sent to them.

Resource managers contact the transaction manager with whom they enlisted to determine the outcome of in-doubt transactions. The transaction manager determines the outcome of each in-doubt transaction and informs the resource managers whether the transaction committed or aborted. If the transaction originated on another system, the transaction manager may need to contact the transaction manager on that system to determine the transaction's outcome.

System or communication failures can leave transactions in doubt for extended periods of time. While a transaction is in doubt, the resources modified by the transaction remain locked and unavailable to others. The system administrator can use the Component Services administrative tool to manually resolve transactions that remain in doubt for too long.

You can use the Component Services administrative tool to view and resolve transaction states. See Manually Resolving Transactions for more information.

MS DTC supports optimizations that make two-phase commit more efficient. These include support for Read-only Transaction Optimization and Transfer of Commit Optimization.


Read-only Transaction Optimization

MS DTC permits resource managers that have read but not updated transaction-protected data to reply read-only during phase one. In this case, the transaction manager will not deliver the second phase notification to the resource manager. This optimization reduces the expense of committing the transaction.

The read-only optimization is also used between transaction managers to optimize the commitment of whole sub-trees of the transaction tree. A transaction manager replies read-only if all of the resource managers and transaction managers subordinate to it reply read-only. This signifies that this transaction manager and the entire sub-tree it controls need not receive notification at phase two.


Transfer of Commit Optimization

MS DTC permits commit coordinator responsibility to be delegated from the coordinating transaction manager to one of its subordinate transaction managers or resource managers. Commit coordinator delegation occurs when the coordinating transaction manager detects that only one subordinate resource manager or transaction manager is enlisted in the transaction.

MS DTC transfers commit coordinator responsibility to the subordinate transaction manager when only one subordinate transaction manager is enlisted in the transaction and no resource manager is enlisted with the current coordinating transaction manager. In this case, the coordinating transaction manager sends a transfer of commit message in place of the phase one message. The transfer of commit message transfers commit coordinator responsibility from the current coordinating transaction manager to its subordinate transaction manager. For example, in the illustration in this topic, the transaction manager on system A has transferred commit coordinator responsibility to the transaction manager on system B.

The transfer of commit optimization is applied recursively. A transaction manager that receives commit coordinator responsibility may transfer commit coordinator responsibility to its subordinate transaction manager, and so forth.

The coordinating transaction manager transfers commit coordinator responsibility to the resource manager when no subordinate transaction manager is enlisted in the transaction and only one resource manager is enlisted in the transaction. The coordinating transaction manager informs the resource manager that it may serve as the commit coordinator when asking the resource manager to prepare at phase one. The resource manager can choose to accept commit coordinator responsibility or not. Some resource managers do not implement this optimization. If the resource manager does not accept commit coordinator responsibility, the transaction manager simply retains commit coordinator responsibility and performs the normal two-phase commit protocol with no optimization. In the preceding illustration, the transaction manager on system B has successfully transferred commit coordinator responsibility to the resource manager on system B.


Components of MS DTC

The components of MS DTC include the MS DTC transaction manager, the MS DTC proxy, the graphical interface for the administrator, the Component Services administrative tool, and the log file. For information about configuring the components of MS DTC, see Configuring MS DTC.

MS DTC Transaction Manager

The MS DTC transaction manager is the process responsible for coordinating MS DTC transactions. One MS DTC transaction manager process is normally present on each Windows system. However, the system administrator can choose to configure a system to depend on an MS DTC transaction manager running on another system. For example, see Configuring the Client Network Protocol.

MS DTC Log

The MS DTC transaction manager maintains an MS DTC log file on disk on its local system. The MS DTC log file captures all of the information that MS DTC must remember regarding transactions. It contains the identity of the transaction. It lists the resource managers that are enlisted with the transaction manager. If the transaction was imported to this node from another node, the log file indicates which MS DTC transaction manager imported the transaction to this node. If the transaction was exported from this node to other nodes, the log file indicates which transaction managers were sent the exported transaction. The log file also indicates the outcome of the transaction and which of the resource managers and transaction managers have been told of the transaction outcome. For more information, see Log File Management.

The information MS DTC maintains in the log file is usually short lived. All information regarding the transaction can be forgotten once the transaction commits or aborts and all of the subordinate transaction managers and resource managers have been told of the transaction outcome. As a result, the MS DTC log file is implemented as a simple circular file. MS DTC writes to the log file sequentially. When it reaches the end of the log file, MS DTC continues writing at the beginning of the file, overwriting obsolete information.

Although most of the information MS DTC maintains in the log file is short lived, some information is long lived. MS DTC avoids overwriting and thereby losing this long-lived information by periodically copying it to the currently active part of the log file. The process of copying long-lived information to the log is referred to as check pointing. MS DTC performs check points periodically.

MS DTC log information is written in binary format. At present there is no mechanism for displaying the contents of the MS DTC log file.

MS DTC Proxy

The MS DTC Proxy DLL (Msdtcprx.dll) implements the OLE Transactions interfaces. OLE Transactions is the Microsoft application programming interface standard for transaction management. OLE Transactions defines the interfaces that application programs and resource managers use to perform transactions. Applications call OLE Transactions interfaces to initiate, commit, abort, and inquire about transactions. Resource managers call OLE Transactions interfaces to enlist in transactions, to propagate transactions from process to process or from system to system, and to participate in the two-phase commit protocol.

Applications and resource managers communicate with the MS DTC transaction manager by calling the OLE Transactions interfaces implemented by the MS DTC proxy.

MS DTC Administration User Interface

The Component Services administrative tool implements the graphical user interfaces you can use to configure, monitor, and manage MS DTC. The Component Services administrative tool communicates with the MS DTC transaction manager via RPC. Refer to Distributed Transaction Administration Tasks for Component Services administrative tool tasks.

The Component Services administrative tool can be used to manage an MS DTC transaction manager on either a local or a remote system. This makes it possible to manage a collection of MS DTC systems from a central location.

MS DTC Files

MS DTC consists of the following files:

File | Description
Msdtc.exe | MS DTC console program
Msdtclog.dll | MS DTC log manager DLL
Msdtcmgr.exe | MS DTC user interface host program
Msdtcprf.h | MS DTC performance monitor header file
Msdtcprf.ini | MS DTC performance monitor .ini file
Msdtcprx.dll | MS DTC OLE Transactions interface proxy DLL
Msdtctm.dll | MS DTC transaction manager DLL
Msdtcui.dll | MS DTC administrative component DLL
Mtxclu.dll | MS DTC and MTS clustering support DLL.
Txfaux.dll | Support routines for TXF
Xolehlp.dll | MS DTC helper APIs DLL


MS DTC Configuration

You can configure MS DTC in several ways. Typically, MS DTC is installed on each Windows 2000 system. In this case each system has its own instance of MS DTC (see Configuring Your Network to Support MS DTC and Performing Distributed Transactions with Windows 95, Windows 98, or Windows NT). Alternatively, two or more systems may share a single instance of MS DTC (See Local MS DTC Transaction Manager on a Windows 2000 System and Remote MS DTC Transaction Manager on a Windows 2000 System). In some cases this can be more efficient than having an instance of MS DTC on each system. On a server cluster of Windows 2000 systems, a single instance of MS DTC services the entire cluster (see MS DTC Transaction Manager on a Windows 2000 Server Cluster). These configuration options are described in more detail in this topic.

Supporting Integrated Security

If you use integrated security, you must configure MS DTC to run under a login ID and password authorized to connect to your Oracle database. Integrated security allows an Oracle database to rely on Windows 2000 authentication to validate database users. This permits a user to log in to Oracle without supplying a separate login ID or password. Users can maintain one login ID and password for both Windows 2000 and Oracle.

If your components always supply a login ID and password when connecting to Oracle databases, you are not using integrated security. This is true whether your applications specify the login ID and password directly or indirectly through a DSN. In either event, you are not using integrated security and do not need to configure MS DTC to run under a login ID and password to connect to an Oracle database.

If you use integrated security, you must configure MS DTC to run under a login ID and password authorized to connect to your Oracle database. This is required because during database recovery, MS DTC opens your Oracle database to tell it the outcome of in-doubt transactions.

MS DTC Services

MS DTC provides two types of services: "essential services" and "optional services." Essential services are critical to the functioning of the Windows system. MS DTC fails to start if any essential MS DTC service fails to start. Other MS DTC services are "optional services." When MS DTC starts, it attempts to start these optional services. If these services start, they become available to the clients of MS DTC. If the optional services fail to start, then any attempt to use these services will be rejected with an error. You can stop and restart MS DTC to start optional services a second time. For step-by-step details on starting or stopping MS DTC, refer to Starting and Stopping MS DTC.

MS DTC also uses the following system services.

NTLMSSP

MS DTC uses the NTLMSSP service to encrypt the XA database open string that it stores in the MS DTC log file. MS DTC uses the XA open string when it opens an XA database to perform recovery. The open string is encrypted to protect any user ids and passwords that may be present in the open string.

RPCSS

MS DTC uses the RPCSS service to communicate between MS DTC components.

Network Connection Configuration

If an application performs transactions spanning two or more computers, you must ensure that these computers are configured to communicate with each other (see Configuring MS DTC).

MS DTC can only propagate transactions from one system to another if the MS DTC process on the first or primary system can communicate with the MS DTC process on the secondary system. However, a network configuration problem on either system can prevent the MS DTC processes from successfully communicating with one another. This will result in a "Failed to enlist error" on applications. For these types of messages, see Dealing with MS DTC Problems.


Configuring Your Network to Support MS DTC

All MS DTC process-to-process communication takes place using Local Remote Procedure Calls (LRPC), Remote Procedure Calls (RPC), or the Transaction Internet Protocol (TIP).

LRPC

MS DTC always uses LRPC when communicating between two processes on the same system. For example, LRPC is used when the MS DTC Proxy is communicating with its local MS DTC transaction manager. MS DTC uses LRPC for local communication because LRPC is very efficient.

RPC

MS DTC uses RPC when communicating between processes on different systems. For example, the MS DTC Proxy uses RPC when communicating with an MS DTC transaction manager on another system. This occurs when the MS DTC Proxy is running on one node in the cluster and the MS DTC transaction manager is running on another node in the cluster. It also occurs when MS DTC is configured to rely on a remote transaction manager. Similarly, an MS DTC transaction manager uses RPC when communicating with an MS DTC transaction manager on another system.

MS DTC RPC communication can occur over TCP/IP, SPX, and NetBEUI transports. MS DTC selects the first transport that is common to the two systems that need to communicate. The preferred transport for MS DTC is TCP/IP. If TCP/IP cannot be used, MS DTC attempts to use SPX and NetBEUI, in that order. If MS DTC cannot find a transport that is common to both systems, it reports the following error in the application event log:

MS DTC is unable to communicate with MS DTC on a remote system. No common RPC protocol is supported between the two systems. Please ensure that one or more of the following RPC protocols are common to both systems: TCP/IP, SPX, or NetBEUI.

TIP

MS DTC can use the Transaction Internet Protocol (TIP) to communicate between transaction managers on different systems. TIP is based on TCP/IP and uses port 3372.

MS DTC selects TIP when an application program or resource manager explicitly uses the TIP OLE Transaction interfaces. MS DTC also uses TIP when TIP is the only communication protocol common to both platforms. TIP is typically used when MS DTC is used in conjunction with transaction managers from other companies.


Performing Distributed Transactions with Windows 95, Windows 98, or Windows NT

If you wish to perform MS DTC distributed transactions between systems running Windows 2000 and Windows NT 4.0, you must install MS DTC version 1998.08.762.0 or later on your Windows NT 4.0 systems. This is essential because MS DTC on Windows 2000 uses a new message protocol when communicating between one MS DTC system and another. MS DTC version 1998.08.762.0 is the version of MS DTC that shipped with Windows NT 4.0 Service Pack 4. It has been enhanced to support the new message protocol.

MS DTC on Windows 2000 supports limited interoperability with Windows 95, Windows 98, and Windows NT 3.51. An MS DTC transaction can be propagated from a Windows 2000 system to a Windows 95, Windows 98, or Windows NT 3.51 system, but not vice versa. For example, a component in a COM+ application running on Windows 2000 can invoke a Microsoft SQL Server database running on Windows 95, Windows 98, or Windows NT 3.51. Similarly, a Microsoft SQL Server stored procedure on a Windows 2000 system can invoke a Microsoft SQL Server stored procedure on Windows 95, Windows 98, or Windows NT 3.51 under distributed transaction control.

An MTS component running on Windows 95, Windows 98, or Windows NT 3.51 can not invoke a SQL Server database running on Windows 2000. Also, a Microsoft SQL Server stored procedure on Windows 95, Windows 98, or Windows NT 3.51 can not invoke a Microsoft SQL Server stored procedure on a Windows 2000 system under distributed transaction control.


Local MS DTC Transaction Manager on a Windows 2000 System

The MS DTC transaction manager, MS DTC Proxy, and the Component Services administrative tool are always installed with Windows 2000. As a result, every Windows 2000 system is capable of performing transactions through its local MS DTC transaction manager.

If an application program on the system calls the BeginTransaction method, the local MS DTC transaction manager on that system will initiate and coordinate an MS DTC transaction. When a resource manager participates in the transaction, it enlists with its local MS DTC transaction manager.

The MS DTC transaction manager maintains an MS DTC log file on a local disk volume.


Remote MS DTC Transaction Manager on a Windows 2000 System

Two or more non-clustered Windows systems can share a single MS DTC transaction manager. In the following figure, system B contains an MS DTC transaction manager and its log file. Transactional applications and resource managers running on system B communicate with their local MS DTC transaction manager running on system B.

System A is configured to use the MS DTC transaction manager on system B. When a transactional application or resource manager on system A calls an MS DTC function, the MS DTC Proxy on system A forwards the request to the MS DTC transaction manager on system B. The transaction manager on system B acts as the transaction manager for all transactions on system A and system B.

Transactions can be more efficient when two or more systems are configured to share a single MS DTC transaction manager. If a transaction touches both nodes, the transaction manager only does a single log write. Had each system had its own transaction manager, each would have written its own log records.


MS DTC Transaction Manager on a Windows 2000 Server Cluster

The MS DTC transaction manager, MS DTC Proxy, and Component Services administrative tool are always installed on each node of a Windows 2000 server cluster as part of Windows 2000 setup. When clustering the systems, you must run the COM Cluster Wizard (Comclust.exe) to configure MS DTC in clustered mode.

The Cluster Wizard makes the following changes to the MS DTC configuration:

  • It creates an MS DTC resource in a resource group containing a shared disk resource and a network name resource.
  • It creates an MS DTC log file on the shared disk contained in the MS DTC resource group. Placing the MS DTC log file on the shared disk makes it possible for the MS DTC transaction manager to access the MS DTC log file from any system in the cluster.
  • It copies critical MS DTC registry entries to the shared cluster registry.

When MS DTC is running in clustered mode, only one node in the cluster runs the MS DTC transaction manager at a time.

Any process running on any node in the cluster may use MS DTC. These processes simply call the MS DTC Proxy in the normal way and the MS DTC Proxy automatically forwards MS DTC calls to the MS DTC transaction manager that is controlling the entire cluster.

If the node running the MS DTC transaction manager fails, the MS DTC transaction manager is automatically restarted on another node in the cluster. The newly restarted MS DTC transaction manager reads the MS DTC log file on the shared disk to determine the outcome of pending and recently completed transactions. Resource managers reconnect to the MS DTC transaction manager and perform recovery to determine the outcome of in-doubt transactions. Applications reconnect to MS DTC so they can initiate new transactions.

For example, in the preceding illustration, the MS DTC transaction manager is active on system B. The application program and resource manager on system A call the MS DTC proxy. The MS DTC Proxy on system A forwards all MS DTC calls to the MS DTC transaction manager on system B.

If system B fails, the MS DTC transaction manager on system A will take over. It will read the MS DTC log file on the shared disk, perform recovery, and then serve as the transaction manager for the entire cluster.


Managing MS DTC from a Remote System

To manage MS DTC from a remote system, you must consider the following scenarios:

  • Managing MS DTC from a remote Windows 2000 or Windows NT 4.0 system
  • Managing MS DTC from a remote Windows 95 or Windows 98 system
  • Security Considerations when remotely managing MS DTC

Managing MS DTC from a remote Windows 2000 or Windows NT 4.0 system

You can administer MS DTC on a Windows 2000 system from a remote Windows 2000 or Windows NT 4.0 system.

You cannot configure or reset the MS DTC log file from a remote system. The Component Services administrative tool updates the MS DTC log file directly thus it must run on the system where the log file resides.

Managing MS DTC from a remote Windows 95 or Windows 98 system

You can administer MS DTC on a Windows 2000 system from a remote Windows 95 or Windows 98 system.

You cannot configure or reset the MS DTC log file from a remote system. The Component Services administrative tool updates the MS DTC log file directly, so it must run on the system where the log file resides.

You cannot start or stop MS DTC from a remote Windows 95 or Windows 98 system.

Security Considerations when remotely managing MS DTC

You must be an administrator on the Windows 2000 system you are managing remotely.


Log File Management

MS DTC uses a log file to monitor and store statistics for distributed transactions. The log file is a critical part of transaction management because it stores information about unresolved transactions — information that the MS DTC uses to resolve transactions in the event of system failures.

Log File Size and Location Can Affect System Performance

To manage system performance, you may need to reset or change the log file size and/or location. The size of the MS DTC log file determines the maximum allowable number of concurrent transactions. (On Windows 2000 the default log file size is 4 MB.) Once a transaction has committed or aborted, it is deleted from the log file.

If the log file becomes full, the transaction manager on the local server cannot accept a new transaction until space to record the new transaction becomes available. You can balance the transaction load on a specific computer running MS DTC. For example, if the number of current transactions approaches the historical maximum, you can increase the size of the log file to allow for more transactions. Conversely, if the number of current transactions is well below the maximum, you can decrease the size of the log file to conserve disk space. You may also be able to improve performance by moving the log file to location where disk space is high or processing demands are low.

Choosing the MS DTC Log File Location

The MS DTC log file is created in its default location when MS DTC is installed. On Windows 2000 and Windows NT, the log file is placed in the %windir%\system32\DTCLog directory by default. You may find that you can enhance your system by specifying a new location for the log file. The following guidelines give more detail.

  • Performance — On extremely high performance transaction processing systems you may wish to place the MS DTC log file on a dedicated disk device or on a device with relatively little other traffic. However, on most systems the MS DTC log file can be located on any disk with free space that is not in use excessively.
  • Reliability — You should put the MS DTC log file on a RAID-1 device for maximum reliability. Losing the MS DTC log file may cause MS DTC to lose track of pending transactions. This may affect the data consistency of the transaction-protected databases, message queues, and files coordinated by MS DTC.

    In RAID-1, log writes are made to both the primary disk and to a mirror copy. Because the writes are made concurrently, the elapsed time for log writes is little more than that for a write to a single device. Because MS DTC log writes are synchronous and sequential, they are ideally suited to RAID-1. RAID-1 is also ideal for the MS DTC log file because it provides fault tolerance. If one of the drives in the mirrored pair fails, MS DTC continues using the surviving disk drive.

    RAID-1 can be implemented through either hardware or software. Windows 2000 provides RAID-1 through software. Using the Windows 2000 RAID-1 capability is normally sufficient since it imposes little processing overhead on your system. Using a hardware-based RAID-1 solution normally offer only marginally better performance than the Windows 2000 software-based implementation of RAID-1.

  • Clustered systems — On a clustered system the MS DTC log file must be located on a shared disk. This permits the MS DTC transaction manager to access the log file regardless of which cluster node it is running on.

Choosing the MS DTC Log File Size

The size of the MS DTC log file determines how many transactions can be active concurrently. Once a transaction has committed or aborted, it is automatically deleted from the log file.

If the log file becomes too full, MS DTC stops initiating new transactions and allowing enlistment in existing transactions. Calls to the BeginTransaction method are rejected with the error XACT_E_LOGFULL. Calls by resource managers to enlist are also rejected with the error XACT_E_LOGFULL. If you experience this error, you should increase the size of the MS DTC log file.

On Windows 2000 and Windows NT, the default MS DTC log file size is 4 MB. On Windows 95 and Windows 98 the default MS DTC log file size is 1 MB.

You can use the following guidelines to determine the size of your MS DTC log file. Allocate 1 MB of log space for every 1,000 transactions that are active concurrently. Allocate 1 MB of log space for every 500 Oracle, IBM DB2, Informix, Sybase, or CA Ingres database connections your applications open concurrently.

These guidelines are conservative. The actual amount of disk space that each MS DTC log file record requires depends upon how many resource managers and subordinate transaction managers are enlisted in the transaction. In addition, MS DTC maintains large reserves of available space in the MS DTC log file to ensure that it always has adequate log space to commit or abort any transaction that it has previously initiated.

For most systems, the default MS DTC log file sizes are safe and adequate.

Resetting the MS DTC log file

While you must reset the MS DTC log file to relocate it to another device or to change its size, you should not do so under most normal circumstances. Doing so may cause MS DTC to lose track of pending transactions, which may affect the consistency of the transaction-protected databases, message queues, and files coordinated by MS DTC.

It is not necessary to reset the MS DTC log file to reclaim disk space within the file because MS DTC does this automatically. Once a transaction has successfully committed or aborted, MS DTC notes that the log records are no longer needed and it eventually reuses the space for other transactions

Before altering the MS DTC log file, ensure that there are no transactions in the In Doubt, Cannot Notify Abort, or Cannot Notify Commit state. Refer to Transaction State Resolution for more information.

Refer to changing the size or location procedures in Configuring the MS DTC Log File section if you wish to change log file attributes.

Note that you cannot reset the MS DTC log file on a remote system. The Component Services administrative tool updates the MS DTC log file directly thus it must run on the system where the log file resides.

For step-by-step information on resetting the MS DTC log file, see Resetting the MS DTC Log File.

Damaged Log Files Cannot Be Restored

If the MS DTC log file is damaged or lost, it cannot be restored, copied from another system, or reinitialized without causing potentially serious data corruption. The MS DTC log file contains critical information regarding transaction outcomes. The information in the MS DTC log is extremely volatile — information that, once a few seconds old, is almost certainly out of date and largely useless for recovery purposes. Because of this, it makes no sense to back up and restore the MS DTC log file.

Caution If the MS DTC log file is lost, the only alternative is to reinitialize the MS DTC log file through the Component Services administrative tool, after copying this file from the CD.

The only safe alternative is to place the MS DTC log file on a failsafe disk device such as a raid array. If the log file is lost despite this precaution, the only alternative is to reinitialize the log file. By doing this, the system administrator is explicitly specifying that the consistency of the underlying transactional resource managers is potentially being compromised.

Coping with a Lost or Damaged MS DTC Log File

If the MS DTC log file is lost, the only alternative is to reinitialize the log file through the Component Services administrative tool. By doing this, the system administrator is explicitly specifying that the consistency of the underlying transactional resource managers may be compromised. Such a consistency problem can occur if the MS DTC log file is re-initialized while committed transactions remain in doubt. In this case, a resource manager that is in doubt may erroneously abort the transaction when it eventually performs recovery. Consider the following example:

Assume that an application updates two resource managers under MS DTC transaction control and commits the transaction. Assume both resource managers successfully complete phase one but one of the resource managers fails before receiving the commit notification during phase two. In this case, the first resource manager commits the transaction while the second resource manager remains in doubt about the transaction outcome. If the MS DTC log file is lost before the second resource manager can perform recovery, all record of the committed but in-doubt transaction is lost. When the second resource manager is restarted, it will inquire about the in-doubt transaction. MS DTC will assume that the transaction aborted because there is no record of the transaction in the newly initialized log file. MS DTC will inform the second resource manger that it could find no record of the transaction and that the resource manager should assume that the transaction aborted. This is a natural consequence of the "Presumed Abort" logging protocol upon which modern transaction managers rely. As a result, the first resource manager will commit the transaction while the second resource manager will abort the transaction.

If the MS DTC log file is lost or damaged
  1. Use your resource manager administrative tools to determine if your resource manager is in doubt about any MS DTC transaction outcome.
  2. Use your resource manager administrative tools to manually force any unresolved transactions to commit or abort. Unfortunately, determining transaction outcomes may be difficult without the MS DTC log file. You should resolve all in doubt transactions before re-initializing the MS DTC log file and restarting MS DTC. Any in doubt transactions you do not resolve will be aborted when MS DTC is restarted and recovery is performed.
  3. Click Reset Log to reinitialize the log file. If a log file already exists in the location specified by the drive and directory, Reset Log deletes the current log file.
  4. Click Start to restart MS DTC.


Transaction State Resolution

Distributed transactions are designed to ease failure recovery in distributed applications — where failure can occur at the client, the server, and the network connection between them. As a result, an important part of transaction management is resolving situations in which a transaction was left in an unresolved state after a system failure.

Transactions Can Remain Unresolved After a System Failure

Normally, MS DTC systems automatically resolve most transactions that stream across the system. On occasion after a failure, some systems cannot reconnect during recovery, leaving unresolved transactions. On other occasions, a faulty application program may cause transactions to get "stuck" and leave unresolved transactions. During those times, you can monitor and manually resolve such transactions by using knowledge of their current state. The following information describes the transaction state resolution process.

There are three types of distributed transaction states that may become stuck or unresolved: In Doubt, Cannot Notify Abort, and Cannot Notify Commit. You can use the Transaction List in the Component Services administrative tool to resolve in-doubt transactions by choosing one of the following commands:

  • Commit — Forces the transaction to commit.
  • Abort — Forces the transaction to abort and roll back to its original state.
  • Forget — Deletes a committed or aborted transaction from the DTC log.

For information on the steps a transaction manager takes after a failure, see How MS DTC Handles Computer Failures.

For descriptions of all transaction states, see MS DTC Transaction States.

For a description of a possible failure scenario, see Example: Transaction Resolution After System Failure.

Transaction Timeout Period

You can set a timeout period within which transactions are automatically aborted if they do not complete. In this way, you can prevent incorrectly written transaction programs from acquiring and holding transactional resources indefinitely. For example, the records that a transaction updates in a Microsoft SQL Server database are locked for the duration of the transaction. If the transaction program loops or deadlocks, the transaction timeout prevents the database records from being held too long. The default transaction timeout period is 60 seconds. See Configuring the Transaction Timeout Period.

For a general description of messages generated by MS DTC, see Event Messages.


How MS DTC Handles Computer Failures

If a computer fails and then restarts, the transaction manager at that computer will normally determine the outcome of all in-doubt transactions. The following list includes the actions that a transaction manager will ordinarily take after a failure.

  • For transactions for which it was the commit coordinator, the transaction manager reads its log file to determine the outcome.
  • For incoming transactions from other systems, the transaction manager reads the log file to determine if it was previously notified of the outcome of the transaction.
  • For incoming transactions that remain in doubt, the transaction manager queries the incoming transaction manager to learn the outcome of the transaction.
  • The transaction manager also responds to queries from other transaction managers regarding in-doubt outgoing transactions sent to them. This is similar to the protocol that transaction managers and resource managers follow at restart. The transaction manager determines the outcome of each in-doubt transaction and, when asked, tells the resource managers the transaction's outcome.

For information on resolving in-doubt transactions that become "stuck," refer to Example: Transaction Resolution After System Failure.


Example: Transaction Resolution After System Failure

When systems involved in transactions are restarted and connections restored after a system or connection failure, MS DTC will ordinarily automatically resolve the transactions. However, MS DTC cannot resolve transactions if the systems are down or connections are not reestablished. In this case, you can manually resolve transactions that are in the In Doubt, Cannot Notify Abort, or Cannot Notify Commit state.

For task-oriented information about resolving these transactions, refer to Manually Resolving Transactions.

The following example illustrates a situation in which a communication line fails between two computers on the network. Once a transaction has been manually committed or aborted, often it is necessary also to manually force a computer to "forget" the transaction, which deletes the transaction from the local MS DTC log file.

In this example, the following conditions are assumed:

  • The MS DTC on computer A is the commit coordinator.
  • The lines of communication along which the two-phase commit protocol is conducted proceed sequentially from computer A to computer D.
  • The first phase of the two-phase commit protocol has concluded, the commit coordinator has decided to commit the transaction, and has written a COMMITTED record to the MS DTC log file on computer A..
  • Communication has failed between computers B and C during the second phase of the two-phase commit protocol. Computers C and D remain in doubt regarding the transaction's outcome.
  • It is difficult or impossible to restore communication between systems B and C.

The transaction is left in the following unresolved state:

Because the line of communication between computers A and B is still intact, both systems have committed the transaction. Computer A has committed and forgotten the transaction; it was permitted to forget the transaction once B acknowledged receipt of the commit notification. Computer B has committed the transaction but it must remember the transaction outcome until C knows the outcome. Computer C is in doubt about the transaction's outcome. Computer D is prepared.

To resolve the transaction (and thereby release the database locks on computers C and D), the system administrator forces computer C to commit the transaction (see the following illustration).

Because the line of communication between computers C and D is still intact, the forced commit on computer C allows the transaction to commit on both computers C and D. Computer D can now release its database locks and forget the transaction. Once computer D confirms to computer C that it has committed and forgotten the transaction, computer C can also forget the transaction.

The transaction is now committed on all computers. However, computer B does not know that computer C has committed the transaction because the connection between the two systems remains down. Computer B continues to remember the transaction. To complete the transaction, the system administrator forces computer B to forget the transaction (see the next illustration). The two-phase commit protocol has been manually concluded, and the transaction is complete.

Note Because of the outgoing-incoming communication pattern of the two-phase commit protocol, you should manually resolve transactions on computers immediately adjacent to the break in communications. Therefore, in the preceding example, the forced commit occurs on computer C (not D), and the forced forget occurs on computer B (not A).

If you choose to commit the transaction, you must always force the commit on C (the subordinate) before performing the forced forget on B (the superior). If you first forced B to forget and communication was then restored between B and C, the system might automatically abort the transaction on C before you could force it to commit on C. This would result in an inconsistent transaction outcome and may result in resource manager inconsistency.


MS DTC Transaction States

As transactions occur, the Component Services administrative tool tracks their progress as a set of states. You can use these states to monitor transactions and to manually resolve those that may become stuck in intermediate states such as In Doubt, Cannot Notify Commit, Cannot Notify Abort, and so on. For information on how to get transaction state information and to resolve transactions, see Manually Resolving Transactions.

A transaction may be in one of the states in the following alphabetized list.

Aborted

The transaction has aborted. All participants have been notified or are currently inaccessible. Once a transaction has aborted, it is immediately removed from the list of transactions in the MS DTC Transactions window. It is not possible to change the transaction outcome at this point.

Active

The transaction has been started and is under way. It is not possible to change the transaction outcome at this point.

Cannot Notify Abort

The commit coordinator has notified all connected subordinates that the transaction has aborted. However, an IBM LU 6.2 transaction manager is enlisted in the transaction, the connection to that transaction manager has failed, thus the abort notification cannot be delivered to that transaction manager. You can force MS DTC to forget the transaction by right-clicking in the Transaction List window, pointing to Resolve, and then clicking Forget.

Use caution to not manually forget a transaction until you have read Manually Resolving Transactions.

Cannot Notify Commit

The commit coordinator has notified all connected participants that the transaction has committed. However, some subordinates cannot be notified that the transaction has committed because they are currently inaccessible. This transaction state also occurs when MS DTC must inform a non-Microsoft transaction manager, such as IBM LU 6.2 or Tuxedo, that a transaction has committed but is unable to do so because the connection to that transaction manager has failed. You can force MS DTC to forget the transaction by right-clicking in the Transaction List window, pointing to Resolve, and then clicking Forget.

Use caution to not manually forget a transaction until you have read Manually Resolving Transactions.

Committed

The transaction has committed and all participants have been notified. Once a transaction commits, it is immediately removed from the list of transactions in the MS DTC Transaction List window. It is not possible to change the transaction outcome at this point.

Forced Abort

The administrator forced the in-doubt transaction to abort (see In Doubt). It is not possible to change the transaction outcome at this point.

Forced Commit

The administrator forced the in-doubt transaction to commit (see In Doubt). It is not possible to change the transaction outcome at this point.

In Doubt

The transaction is prepared but the outcome of the transaction is unknown because the remote transaction manager that is acting as the commit coordinator is inaccessible. The commit coordinator may be either an MS DTC transaction manager on another system or a transactions manager from a source other than Microsoft. In either event, MS DTC lost communication with that transaction manager after preparing but before being told the transaction's outcome. The transaction will remain prepared and In Doubt until communication is restored with the superior transaction manager. The system administrator can force the transaction to commit or abort by right-clicking in the Transaction List window, pointing to Resolve, and then clicking Commit or Abort. Once a transaction's outcome is forced, the transaction is designated as Forced Commit or Forced Abort.

Use caution to not manually force an in-doubt transaction until you have read Manually Resolving Transactions.

Prepared

All participants have responded that they have successfully prepared. It is not possible to change the transaction outcome at this point.

Preparing

The application has called commit. The transaction manager has asked the resource managers and subordinate transaction managers to prepare and it is waiting for all of them to acknowledge that they are prepared. It is not possible to change the transaction outcome at this point.

Unknown
The number of attempted transfer of Commits whose reply was lost and therefore cannot be counted as either Committed or Aborted. Please refer to Transfer of Commit Optimization.


Managing XA Transactions

MS DTC can act as either an XA-compliant resource manager or transaction manager.

Managing XA Transactions When MS DTC Is Acting as an XA Resource Manager

When MS DTC is acting as an XA-compliant resource manager, it allows Microsoft SQL Server, Microsoft Message Queue, and other OLE Transactions-compliant resource managers to participate in transactions controlled by X/Open DTP XA-compliant transaction processing monitors such as Encina, TopEnd, and Tuxedo.

MS DTC displays the superior XA Transaction Manager's transaction identifier (XID) in the transaction properties window. This XID can be used to resolve any in-doubt transactions in MS DTC that have an XA Transaction Manager as a superior. You can use the administrative tool for the XA Transaction Manager to determine the outcome of the transaction and force the outcome for the corresponding transaction on the subordinate MSDTC. Note, please attempt to reconnect the XA Transaction Manager with MS DTC before manually trying to resolve the transaction.

Managing XA Transactions When MS DTC Is Acting as an XA Transaction Manager

When MS DTC is acting as an XA-compliant transaction manager, it allows Oracle, IBM DB/2, Sybase, Informix, and other XA-compliant resource managers to participate in transactions controlled by MS DTC. When displaying information for transactions spanning XA-compliant resource managers, MS DTC does not display the XID of the transaction. Instead MS DTC just displays the OLE Transactions Unit of Work identifier (UOW) for the transaction. There is a one-to-one mapping between the UOW and the XID, as follows:

An XID is defined as the struct:

struct xid_t
{
  long formatID;            /* format identifier */
  long gtrid_length;          /* value not to exceed 64 */
  long bqual_length;          /* value not to exceed 64 */
  char data[128];
}

An XID corresponding to a OLE Transaction has the formatID field set to 0x00445443, the gtrid_length field set to 16, and a the first 16 bytes of the data field set to the UOW.

You can use the administrative tool for the XA-compliant resource manager to correlate transaction in MS DTC.


Managing IBM CICS LU 6.2 Transactions

MS DTC can participate in distributed transactions with IBM systems that support the IBM LU 6.2 protocol. If the connection between the Windows system and the IBM system fails and remains down, a transaction outcome can remain in doubt for an extended period of time. In this event, the IBM system may choose to heuristically commit or abort the transaction. Essentially, this means that the IBM system guesses the transaction's outcome rather than waiting to be told its outcome. Having heuristically committed or aborted the transaction, the IBM system can then release the locks held on behalf of the transaction. This allows other applications to access the records that were updated and locked by the transaction.

When the connection between the Windows system and the IBM system is restored, the MS DTC transaction manager will compare the actual transaction outcome with the IBM system's heuristic decision about the transaction. MS DTC will report the event in the application event log if the IBM system aborted the transaction or reported a heuristic mixed outcome when MS DTC committed the transaction.

If the IBM system mistakenly aborted the transaction or reported a heuristic mixed outcome, or the IBM system aborted the transaction or reported a heuristic mixed outcome when MS DTC aborted the transaction, MS DTC will also report the event in the application event log.


Event Messages

When monitoring transactions, you can use event messages to retrieve information about the transaction system status. MS DTC generates three types of events: error events, warning events, and information events. On Windows 2000 and Windows NT, MS DTC events are recorded in the Windows event log. You can view these events using the Windows 2000 event viewer. Refer to the Windows 2000 documentation for information about the event viewer. See also Viewing Event Messages.

On Windows 95 and Windows 98, MS DTC events are recorded in a text file called Msdtc.txt. This file is located in the \COM+Logs sub-directory of the Windows directory.

The following table lists and describes event types.

Event Type | Description
Error Events | A serious error has occurred, such as log file corruption.
Warning Events | An abnormal event has occurred.
Information Events | A normal event has occurred, such as MS DTC startup or shutdown.


Transaction Statistics Window Contents

The MS DTC Transaction Statistics window contains three groups of information, as described in this topic.

Current Group
Statistic | Description
Active | The current number of active transactions.
Max. Active | The highest number of concurrently active transactions since MS DTC was last started.
In Doubt | The current number of transactions about which the transaction manager is in doubt.

Aggregate Group
Statistic | Description
Committed | The cumulative total of committed transactions. This number does not include forced (manually resolved) commits.
Aborted | The cumulative total of aborted transactions. This number does not include forced (manually resolved) aborts.
Forced Commit | The cumulative total of committed transactions that were manually committed.
Forced Abort | The cumulative total of aborted transactions that were manually aborted.
Total | The cumulative total of all transactions.

Each time you stop and restart MS DTC, the aggregate statistics are reset to zero.

Response Times Group

Response time is the duration of a transaction from the point that it began to the point that it committed. Aborted transactions and transactions whose outcomes were forced to commit or abort are not included in this statistic. The Response Times group displays the minimum, average, and maximum transaction response times in milliseconds.

Each time you stop and restart MS DTC, the average and maximum transactions response time statistics are reset to zero.


Understanding OLE, LU 6.2, and TIP Transaction List Views

Occasionally, if a communication line fails or a faulty distributed transaction application leaves unresolved transactions, you may need to view transaction lists and properties, control which transactions are displayed, set transaction timeout periods, and control how often transactions are updated.

Since transactions are normally fleeting in real time, you can only view transactions that are relatively long-lived. That is, in some cases, transactions get "stuck," and may be present for long periods of time. In many cases, a timeout period for a transaction will expire and many of those transactions will be forced to abort. In some cases, however, a system will fail and attempt to recover, but does not connect to a resource manager. In this case, recovery was not complete and the transaction is left in an In Doubt or failed to notify state. In these cases, you must view the transaction list before you can resolve them.

Transaction Properties for OLE Transactions

For each OLE transaction, the Superior/Subordinate column displays the name of the superior transaction manager, if any, followed by the names of subordinate transaction managers and resource managers.

If the transaction originated on this system, then this transaction manager is serving as the global commit coordinator and there is no superior. In this case, the first entry in the Superior/Subordinate column will be <no superior>. If the transaction originated on another system, the name of the superior system is displayed in the Superior/Subordinate column. The heading appears only when there is actually a transaction in the list.

The names of the subordinate transaction managers and resource managers are listed following the superior transaction manager. For each subordinate OLE Transactions transaction manager, the Superior/Subordinate column contains the name of the subordinate transaction manager system. For each subordinate OLE Transaction resource manager, the Superior/Subordinate column contains the resource manager's displayable name. The resource manager may supply its displayable name when it first connects to MS DTC. MS DTC displays this name if the resource manager supplied it.

If the superior or subordinate is an OLE Transactions transaction manager or resource manager, then the ID column of the transaction properties will be empty. If the superior or subordinate is an LU 6.2, TIP, or XA transaction manager, then the ID column of the transaction properties will display the transaction identifier of the LU 6.2, TIP, or XA transaction. For more information regarding LU 6.2, TIP, and XA transactions, refer to the sections that follow.

Transaction Properties for LU6.2 Transactions

For each IBM LU6.2 transaction, the LU Pair is displayed in the Superior/Subordinate column of the transaction properties and the Logical Unit of Work ID is displayed in the ID column of the transaction properties.

The LU Pair consists of the fully-qualified Microsoft SNA Server LU followed by the fully-qualified IBM SNA LU. Each fully-qualified LU consists of the Network Name followed by the LU name. Currently the Microsoft system is always the transaction coordinator and the IBM system is always the subordinate.

The Logical Unit of Work ID consists of the fully qualified Microsoft SNA Server LU, followed by the Logical Unit of Work instance number and the Logical Unit of Work sequence number. The instance number and sequence number are displayed in hexadecimal form. You can correlate these values with the corresponding values on your IBM system.

Transaction Properties for TIP Transactions

For each TIP transaction, the TIP transaction manager's address is displayed in the Superior/Subordinate column of the transaction properties and the TIP transaction ID is displayed in the ID column of the transaction properties.


Distributed Transaction Administration Tasks

Administrative tasks for distributed transactions include configuring your system to support distributed transactions, monitoring transactions and managing performance, and resolving problems associated with system failures.

Use the following links for step-by-step details.

Topic | Description
Installing MS DTC | Provides step-by-step solutions for various specialized installation cases.
Configuring MS DTC | Provides links to information that will help you configure MS DTC for your network and application needs.
Managing MS DTC | Offers links to information on managing the MS DTC log file, manually resolving transactions, administering MS DTC remotely, and more.
Monitoring MS DTC Performance | Provides links to topics on monitoring transactions and viewing transaction properties and statistics.
Dealing with MS DTC Problems | Lists troubleshooting steps you can take if you receive the "Failed to enlist" message.
Obtaining MS DTC Support | Lists information to provide when you are seeking MS DTC assistance from the Microsoft product support organization.


Installing MS DTC

MS DTC is installed automatically when you install Windows 2000. However, there are certain installation situations that require special consideration if MS DTC is to be used on the system.

Use the following links for step-by-step details.

  • Resolving Transactions Before Upgrading to Windows 2000
  • Configuring MS DTC on a Windows 2000 Cluster
  • Reinstalling MS DTC

Also, even though MS DTC is a component of Windows 2000, and is automatically installed and configured when Windows 2000 is installed, there are three significant MS DTC enhancements in the Windows 2000 release that you should be aware of when installing:

  • MS DTC now stores XA-related recovery information in the MS DTC log file — rather than the DTCXATM.log file — and the latter has been eliminated.
  • Upgrading a Windows 95 or a Windows 98 system to a Windows 2000 system causes MS DTC to use a new MS DTC log file.
  • The MS DTC network message protocol has been enhanced. This affects interoperability with MS DTC on existing Windows 95, Windows 98, and Windows NT systems.


Resolving Transactions Before Upgrading to Windows 2000

If you used Microsoft Transaction Server (MTS) or Microsoft SQL Server 7.0 on your Windows 95 or Windows 98 system and you wish to upgrade that system to Windows 2000, you must take the following precautions before upgrading. This is essential because upgrading the system to Windows 2000 will cause MS DTC to use a new MS DTC log file. Thus, all unresolved transactions will be lost after the upgrade.

Resolving XA Transactions

If you used Microsoft Transaction Server (MTS) on Windows 95, Windows NT, or Windows 98, and your MTS application updated an Oracle, IBM DB2, Informix, Ingres, or Sybase database under distributed transaction control, then you must take the following precautions before installing Windows 2000. This is essential because MS DTC now stores XA-related recovery information in a new way. Previously, MS DTC stored XA-related recovery information in a separate DTCXATM.log file. On Windows 2000, XA recovery information is stored in the MS DTC log file, along with all other MS DTC recovery information. The DTCXATM.log file has been eliminated.

Before you install Windows 2000, you must ensure that MS DTC has no XA transactions that are in doubt and require recovery.

To verify that MS DTC has no XA transactions that are in doubt and require recovery
  1. Before upgrading, start the MTS Explorer and use the Transaction List screen to ensure that there are no in-doubt transactions on your system (use the steps for viewing transactions in Viewing Transaction Information). This step and step 2 ensure that there are no unresolved MS DTC transactions affecting your Oracle, IBM DB2, Informix, CA Ingres, or Sybase database.

    Unresolved transactions will be in one of the following states: In Doubt, Cannot Notify Abort, or Cannot Notify Commit.

  2. Use your Oracle, IBM DB2, Informix, CA Ingres, or Sybase database administration tools to ensure that there are no in-doubt database transactions.
  3. If in-doubt transactions are present, you should start MS DTC and your database to allow automatic transaction recovery to take place. If in-doubt transactions that originated from MS DTC remain, use your Oracle, IBM DB2, Informix, Ingres, or Sybase database administration tools to resolve them.

Resolving MS DTC Transactions

Before upgrading to Windows 2000, you must ensure that no unresolved MS DTC transactions are present on the Windows 95 or Windows 98 system you are upgrading.

To verify that no unresolved MS DTC transactions are present
  1. Before upgrading, start the MTS Explorer and use the Transaction List screen to ensure that there are no in-doubt transactions on your system (use the steps for viewing transactions in Viewing Transaction Information). This step and step 2 ensure that there are no unresolved MS DTC transactions affecting your Oracle, IBM DB2, Informix, Ingres, or Sybase database.

    Unresolved transactions will be in one of the following states: In Doubt, Cannot Notify Abort, or Cannot Notify Commit.

  2. If any unresolved transactions are present, you must resolve them using the procedure for Manually Resolving Transactions described elsewhere in this document.


Configuring MS DTC on a Windows 2000 Cluster

When you install Windows 2000, the MS DTC transaction manager, MS DTC Proxy, and Component Services administrative tool are always installed on each node of a Windows 2000 cluster.

When you install and configure the Cluster service on a Windows 2000 system, MS DTC will automatically attempt to configure itself to run as a highly available service. This is because MS DTC can only run as a highly available service when the Cluster service is running.

Prior to upgrading a Windows NT 4.0 cluster to a Windows 2000 cluster you must ensure that the cluster configuration contains at least one resource group with a Network Name resource, an IP Address resource, and a Physical Disk resource. Failing to do this will cause the automatic configuration of MS DTC to fail.

If you encounter this situation after you upgraded to Windows 2000
  1. Configure a resource group with a Network Name resource, an IP Address resource, and a Physical Disk resource.
  2. Run the COM Cluster Wizard (Comclust.exe) on each node in the cluster.

Note that MS DTC does not provide a way to delete a Windows 2000 system from an existing cluster. Note also that if you are upgrading computers with MS DTC for clustering on Windows 2000, upgraded computers must already be running Windows NT 4.0 SP4.


Reinstalling MS DTC

You must re-install MS DTC whenever you install SQL Server 6.5 or any SQL Server 6.5 service pack release. This is necessary because SQL Server setup installs an obsolete version of MS DTC that is incompatible with Component Services on Windows 2000.

To reinstall MS DTC on a Windows 2000 system
  1. Ensure that MS DTC is stopped. Ensure that any services that depend on MS DTC are also stopped, including Component Services, Microsoft SQL Server, Message Queuing, and Microsoft COMTI.
  2. Execute the DTCSetup.exe program that is located in the System32 directory.
  3. Restart any services that depend on MS DTC.

To reinstall MS DTC on a Windows 2000 server cluster
  1. Ensure that the MS DTC cluster resource is stopped using the Cluster Administrator. Ensure that any services that depend on MS DTC are also stopped, including Component Services, Microsoft SQL Server, Message Queuing, and Microsoft COMTI.
  2. Execute the DTCSetup.exe program that is located in the <%Windir%>\System32 directory on each node in the cluster. Do not reboot any system until MS DTC setup has been successfully run on all systems in the cluster. After doing this, you must reboot all systems.
  3. Restart any services that depend on MS DTC.


Configuring MS DTC

To provide support for distributed transactions, you may need to configure MS DTC for manual or automatic operation, configure the network for Windows Clustering, change the UserID under which MS DTC runs, administer remote MS DTC operation, and verify (or troubleshoot) communication between two or more computers.

Use the following links for step-by-step details.

  • Configuring the MS DTC Service
  • Configuring the Default Coordinator
  • Configuring the Client Network Protocol
  • Configuring the MS DTC Log File
  • Configuring MS DTC to Work Through a Firewall
  • Configuring the Transaction Timeout Period


Configuring the MS DTC Service

You can control whether MS DTC is started automatically when the computer is started. You can also control the logon identity under which MS DTC runs.

If you are running Component Services in a clustered environment, see the procedure in Starting and Stopping MS DTC for information on starting and stopping MS DTC on a Windows 2000 cluster.

Configuring MS DTC Startup Type

MS DTC must be started before applications and resource managers can participate in MS DTC transactions. There are three ways that MS DTC can be started, as follows:

  • Start and stop MS DTC manually (only when you need it).
  • Configure MS DTC to start automatically each time the Windows 2000 system is started.

If the applications and resource managers on the system never participate in distributed transactions, there is no need to start MS DTC. In that case, you can disable MS DTC so you have more memory available for other uses.

On Windows 2000 Professional, MS DTC is configured for manual startup by default. On all server versions of Windows 2000, MS DTC is configured for automatic startup by default.

To configure MS DTC for manual or automatic startup using Computer Management
  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Computer Management.
  2. In the console tree of Computer Management (Local), double-click Services and Applications, and then click Services.
  3. In the details pane, double-click Distributed Transaction Coordinator.
  4. In the Distributed Transaction Coordinator Properties (Local Computer) dialog box, on the General tab, in the Startup type box, select Automatic or Manual.
  5. Click OK.

To configure MS DTC for manual or automatic startup using Component Services
  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Component Services.
  2. In the console tree of the Component Services administrative tool, double-click Services.
  3. In the details pane, double-click Distributed Transaction Coordinator.
  4. In the Distributed Transaction Coordinator Properties (Local Computer) dialog box, on the General tab, in the Startup type box, select Automatic or Manual.
  5. Click OK.

This change will not start or stop MS DTC. To start and stop MS DTC manually, see Starting and Stopping MS DTC for instructions.

Configuring the MS DTC Logon Identity

On Windows 2000, MS DTC is configured to run under the identity of the System account by default. You may configure MS DTC to run under another logon identity. You must specify a logon identity that has administrative privileges on the system.

If you use an Oracle XA Resource Manager that relies on the integrated security feature, you must configure MS DTC to run under a login ID and password authorized to connect to that XA Resource Manager. This is required because during recovery, MS DTC connects to the XA Resource Manager to inform it as to the outcome of in-doubt transactions. Examples of an XA Resource Manager include Oracle, IBM DB/2, Informix, Sybase, or CA Ingres databases.

To change the logon identity for MS DTC using Component Services
  1. In the console tree of the Component Services administrative tool, click Services (Local).
  2. In the details pane, double-click Distributed Transaction Coordinator.
  3. On the General tab, under Service status, click Stop.
  4. On the Log On tab, click This Account, and then use the boxes provided to specify a user name and password.
  5. On the General tab, under Service status, click Start to restart MS DTC.
  6. Click OK.

The new logon identity takes effect when you restart MS DTC.

To change the logon identity for MS DTC using Computer Management
  1. In the console tree of Computer Management (Local), double-click Services and Applications, and then click Services.
  2. In the details pane, double-click Distributed Transaction Coordinator.
  3. On the General tab, under Service status, click Stop.
  4. On the Log On tab, click This Account and specify a user name and password.
  5. On the General tab, under Service status, click Start to restart MS DTC.
  6. Click OK.

The new logon identity takes effect when you restart MS DTC.


Configuring the Default Coordinator

By default, each system uses its local MS DTC transaction manager when initiating and coordinating transactions. However, you can configure your machine to use the MS DTC transaction manager of another system as the default transaction coordinator. The MS DTC transaction manager on the specified system is used as the transaction coordinator whenever a client on the local system begins an MS DTC transaction and that client does not explicitly specify a transaction coordinator. The default transaction coordinator coordinates all transactions initiated by Component Services. The default transaction coordinator also serves as the transaction coordinator for all resource managers on the local system that enlist in any MS DTC transaction.

The system you select as the default coordinator should be reliable. The network connection to the default coordinator system should also be reliable. Otherwise, specifying a default coordinator may reduce the availability of MS DTC on your local system. A Windows 2000 cluster running Cluster service is a good choice to serve as the default coordinator. When you configure a Windows 2000 cluster running Cluster service as the default coordinator, you may specify the name of any virtual server running on the cluster.

To configure the default transaction coordinator you must have administrator privileges on both the local system and the system you are designating as the default transaction coordinator. This makes it possible for the local MS DTC system to retrieve the appropriate information from the system registry on the default transaction coordinator system.

To designate a remote system as the default transaction coordinator
  1. In the console tree of the Component Services administrative tool, right-click the computer containing MS DTC, and then click Properties.
  2. In the computer properties dialog box, click the MSDTC tab.
  3. Clear the Use local coordinator check box.
  4. In the Remote Host box, enter the remote system name.

    Or, click Select to display a list of all computers on the network and select the computer you want from the list.

  5. Click OK.

To designate the local system as the default transaction coordinator
  1. In the console tree of the Component Services administrative tool, right-click the computer containing the MS DTC, and then click Properties.
  2. In the computer properties dialog box, click the MSDTC tab.
  3. Select the Use local coordinator check box.
  4. Click OK.


Configuring the Client Network Protocol

When you configure MS DTC to rely on a remote MS DTC transaction coordinator, you can specify which RPC transport the MS DTC Proxy will use to communicate with the transaction coordinator on the remote system. You may choose between TCP/IP, SPX, and NetBEUI. Because it is more widely supported, TCP/IP is the default and recommended protocol for MS DTC.

To configure the client network protocol
  1. In the console tree of the Component Services administrative tool, right-click the computer containing MS DTC, and then click Properties.
  2. In the computer properties dialog box, click the MSDTC tab.
  3. In the Client Network Protocol Configuration box, select TCP/IP, SPX, or NetBEUI.
  4. Click OK.

The new client network protocol setting takes effect immediately. Transactional applications and resource managers that were running before the change are unaffected. Transactional applications and resource managers that start after the change use the new client network protocol.


Configuring the MS DTC Log File

You may configure the location and size of the MS DTC log file. The location of the MS DTC log file can affect the performance and reliability of your system. The log file size determines how many transactions MS DTC can support concurrently.

Caution If you change the size of the log file, the current log file is destroyed and a new log file is created. Before altering the MS DTC log file, verify that the existing log file can safely be deleted by ensuring that there are no transactions in the In Doubt, Cannot Notify Abort, or Cannot Notify Commit state. Refer to Manually Resolving Transactions for more information.

To change the size or location of the log file
  1. In the console tree of the Component Services administrative tool, right-click the computer containing the MS DTC log file, and then click Properties.
  2. In the computer properties dialog box, click the MSDTC tab.
  3. Under Service Control Status for MSDTC, click Stop to stop MS DTC.

    If you do not stop MS DTC, your attempt to reset the log file will generate an MS DTC console message indicating that you cannot perform the requested action.

  4. To change the log file location, under Log Information, in the Location box, enter the new drive and path for the log file.

    Or, click Browse to select a new log file location.

  5. To change the log file size, under Log Information, in the Capacity box, enter the new log file size in megabytes.

    On Windows 2000, the log file size may be between 1 MB and 512 MB. On Windows 95 and Windows 98, the log file size may be between 1 MB and 64 MB.

  6. Click Reset log to alter the MS DTC log location and size.
  7. Under Service Control Status for MSDTC, click Start to start MS DTC.
  8. Click OK.


Configuring MS DTC to Work Through a Firewall

MS DTC can be configured to communicate through firewalls, including network address translation firewalls.

MS DTC uses RPC dynamic port allocation. By default, RPC dynamic port allocation randomly selects port numbers above 1024. By modifying the registry, you can control which ports RPC dynamically allocates for incoming communication. You can then configure your firewall to confine incoming external communication to only those ports and port 135 (the RPC Endpoint Mapper port).

You must provide one incoming dynamic port for MS DTC. You may need to provide additional incoming dynamic ports for other subsystems that rely on RPC.

The registry keys and values described below do not appear in the registry by default; you must add them using the Registry Editor.

To control RPC dynamic port allocation
  1. To start the Registry Editor, from the Start menu, click Run, type regedt32, and click OK.

    You must use Regedt32.exe, rather than Regedit.exe, because Regedit.exe does not support the REG_MULTI_SZ data type required for the Ports named value.

  2. In the Registry Editor, select the HKEY_LOCAL_MACHINE on Local Machine window.
  3. Expand the tree by double-clicking the folders named in the following path:

    HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc

  4. Click the Rpc folder, click the Edit menu, and then click Add Key.
  5. In the Add Key dialog box, in the Key Name box, type Internet, and then click OK.
  6. Click the Internet folder, click the Edit menu, and then click Add Value.
  7. In the Add Value dialog box, in the Value Name box, type Ports.
  8. In the Data Type box, select REG_MULTI_SZ, and then click OK.
  9. In the Multi-String Editor dialog box, in the Data box, specify the port or ports you want RPC to use for dynamic port allocation, and then click OK.

    Each string value you type specifies either a single port or an inclusive range of ports. For example to open port 1025 specify "1025." To open ports 1025 to 1030 inclusive specify "1025-1030." You may specify multiple ports or ports ranges by specifying one port or port range per line. All ports must be in the range of 0 to 65535. If any port is outside this range or if any string is invalid, RPC will treat the entire configuration as invalid.

  10. Follow steps 6 through 9 to add another key for Internet, using the following values:

    Value: PortsInternetAvailable

    Data Type: REG_SZ

    Data: Y

    This signifies that the ports listed under the Ports named value are to be made Internet-available.

  11. Follow steps 6 through 9 to add another key for Internet, using the following values:

    Value: UseInternetPorts

    Data Type: REG_SZ

    Data: Y

    This signifies that RPC should dynamically assign ports from the list of Internet ports.

  12. Configure your firewall to allow incoming access to the specified dynamic ports and to port 135 (the RPC endpoint mapper port).
  13. Restart the system. When RPC restarts it will assign incoming ports dynamically based on the registry values you have specified.

    For example, to open ports 1025 through 1030 inclusive, create the following named values:

    Ports : REG_MULTI-SZ : 1025-1030

    PortsInternetAvailable : REG_SZ : Y

    UseInternetPorts : REG_SZ : Y

For more information concerning using DCOM and RPC with firewalls, consult the excellent white paper by Michael Nelson, "Using Distributed COM with Firewalls." It can be found at http://www.microsoft.com/com/wpaper/dcomfw.asp.


Configuring the Transaction Timeout Period

MS DTC does not allow you to configure a default transaction timeout. Transaction timeouts are set by the application beginning the transaction (for example, Component Services).


Managing MS DTC

MS DTC provides tools through which you can monitor and manage transactions to troubleshoot problems and optimize performance.

Use the following links for step-by-step details.

  • Starting and Stopping MS DTC
  • Viewing Transaction Information
  • Manually Resolving Transactions
  • Resetting the MS DTC Log File


Starting and Stopping MS DTC

MS DTC provides two types of services — "essential services" and "optional services." Essential MS DTC services are critical to the functioning of the Windows 2000 system. MS DTC will not start if any essential MS DTC service fails to start. Other MS DTC services are "optional services." When MS DTC starts, it attempts to start these optional MS DTC services. If these services start, they become available to the clients of MS DTC. If the optional services fail to start, then any attempt to use these services will be rejected with an error. Dividing the services into essential and optional services improves overall system availability. You may choose to stop and restart MS DTC in an effort to restart these optional services.

The following MS DTC services are optional services:

  • Transaction Internet Protocol (TIP).
  • Support for XA-compliant resource managers such as Oracle, IBM DB2, Informix, Sybase, and CA Ingres.

MS DTC can be started and stopped through any of the following:

  • Component Services administrative tool
  • Command prompt
  • Computer Management
  • Cluster Administrator

All of these means of starting and stopping MS DTC have exactly the same effect. Choose whichever you find the most convenient.

Caution If MS DTC fails to start, examine the Windows Event Log to see if any MS DTC-related events are displayed near the time of the failure. MS DTC typically logs an event when it is unable to start successfully. See Viewing Event Messages.

To start or stop MS DTC on Windows 2000 or a server cluster using Component Services administrative tool
  • In the console tree of the Component Services administrative tool, right-click the computer for which you are managing transactions, and then click Start MS DTC or Stop MS DTC.

Note The Component Services administrative tool requires MS DTC to be running in order to commit any configuration changes. If you attempt to change any settings using the Component Services administrative tool when MS DTC is stopped, MS DTC will be restarted. Should you get errors when attempting to use the Component Services administrative tool, verify that MS DTC is started, and if not, restart it.

To start and stop MS DTC on Windows 2000 using Computer Management

The following procedure will not work in clusters.

  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Computer Management.
  2. In the console tree of Computer Management (Local), double-click Services and Applications, and then click Services.
  3. In the details pane, right-click Distributed Transaction Coordinator, and then click Start or Stop.

To start and stop MS DTC on Windows 2000 or a Windows 2000 cluster through the command prompt
  • From the command prompt, enter "msdtc -start" or "msdtc -stop".

To start and stop MS DTC on a Windows 2000 cluster through the Cluster Administrator

The following procedure does not work on a Windows 2000 system that is not clustered.

  1. Run the Cluster Administrator.
  2. Right-click on the MS DTC resource, and then click Bring Online or Take Offline.

MS DTC Failover on a Windows 2000 Clustered System

You can use the Cluster Administrator to force the MS DTC transaction manager to switch from one cluster node to another.

To failover MS DTC on a cluster from the Cluster Administrator
  1. Run the Cluster Administrator.
  2. Right-click the MS DTC resource group that contains the MS DTC resource, and then click Move Group.

The Move Group command takes effect immediately. The MS DTC transaction manager is immediately stopped on the current cluster node and is started on the alternate cluster node. Once restarted, MS DTC performs recovery. During recovery, MS DTC aborts any transaction that was in active state at the time of the failover; it commits or aborts any in-doubt transactions as appropriate. For information on resolving transactions, see Manually Resolving Transactions.


Viewing Transaction Information

Occasionally, if a communication line fails or a faulty distributed transaction application leaves unresolved transactions, you may need to view transaction lists and properties, control which transactions are displayed, set transaction timeout periods, and control how often transactions are updated.

Typically you will only be interested in viewing transactions that may require manual intervention. This includes transactions that are in the Cannot Notify Abort, Cannot Notify Commit, and In Doubt states.

After performing one or more of these tasks, you may wish to view the performance of MS DTC (see Monitoring MS DTC Performance).

For more information about views, see Understanding OLE, LU 6.2, and TIP Transaction List Views.

To view the transaction list
  • In the console tree of the Component Services administrative tool, double-click the computer for which you want to view the transaction list, double-click Distributed Transaction Coordinator, and then click Transaction List.

    You can use this view to see all transactions, their status, and their identifiers. For more information about transaction states, see MS DTC Transaction States. To resolve transactions, see Manually Resolving Transactions.

To change the appearance of the transaction list
  • Right-click the details pane, point to View, and then click one of the following:
Click | To
Large Icons | Display transactions as large icons.
Small Icons | Display transactions as small icons.
List | Display transactions sequentially in a column.
Details | List transactions in a single column and display a column that contains the unit-of-work ID associated with each transaction. This is the transaction's globally unique identifier, and is generated by MS DTC when the transaction begins.

Note You can select a view mode from the toolbar. The Small Icon View and List View display the most transactions at one time. The Property View provides the most information about the transactions, and Large Icon View displays transactions in the most readable format.

You can view transaction properties by right-clicking a selected transaction, and then clicking Properties. The Properties command lists all transaction managers and resource managers that are involved in the transaction.

To view transaction properties in the Component Services administrative tool
  1. In the console tree, click Transaction List.
  2. In the details pane, right-click the transaction whose properties you want to view, and then click View. This page will show you all transactions and their identifiers. To understand their meaning, review MS DTC Transaction States.
  3. Click Properties to list the transaction's parent and its children.


Manually Resolving Transactions

Occasionally, you may need to force a transaction to commit or abort to release locks and make database resources available to other network users and applications. This can be necessary, for example, when a communication line fails between two computers on the network. Once a transaction has been manually committed or aborted, it may be necessary to manually force a computer to "forget" the transaction, which deletes the transaction from the local MS DTC log file.

You can use the transaction list on the parent computer to determine the outcome of a transaction. For information about viewing the transaction list, see Viewing Transaction Information.

To manually resolve transactions
  1. In the console tree of the Component Services administrative tool, double-click the computer for which you want to view the transaction list, double-click Distributed Transaction Coordinator, and then double-click Transaction List.
  2. Right-click the transaction you want to resolve, point to Resolve, and then click Commit, Abort, or Forget.

Resolving the In Doubt State

The In Doubt state indicates that the transaction is on a subordinate MS DTC and that the superior MS DTC is inaccessible. For more information about superior and subordinate transaction managers, refer to Example: Transaction Resolution After System Failure.

To resolve an in-doubt transaction
  1. Use the Transaction List to locate the in-doubt transaction's immediate parent. To view transaction properties, see Viewing Transaction Information.
  2. Locate the superior MS DTC system and use the Transaction List on that system to determine the outcome of the in-doubt transaction, as follows:
    • If the transaction does not appear in the Transactions page, then the transaction has been aborted, and you can abort the transaction on the subordinate system manually.
    • If the transaction appears on the superior system as Cannot Notify Commit, then the transaction has committed, and you can commit the transaction on the subordinate system manually.
    • If the transaction appears on the superior system as Cannot Notify Abort, then the transaction has aborted, and you can abort the transaction on the subordinate system manually.
    • If the transaction is shown as In Doubt on the superior system, use the Transactions page on that system to locate the transaction's next immediate superior. Continue to follow the transaction up the commit tree until you locate the superior system on which the transaction is either not shown (indicating that it aborted), in the Cannot Notify Abort state (indicating that it aborted), or in the Cannot Notify Commit state (indicating that it committed). If the transaction is aborted on the superior system, manually force the transaction to abort on that computer's immediate subordinate. If the transaction is committed on the superior system, manually force the transaction to commit on the subordinate system.
  3. Once you have either manually committed or aborted the transaction on the subordinate system, manually force the immediate superior to forget the transaction.

Resolving the Cannot Notify Abort State

The Cannot Notify Abort state indicates that the transaction has aborted, but a subordinate IBM LU6.2 transaction manager has not been notified of the transaction's outcome. You can manually resolve the transaction as follows.

To display the Cannot Notify Abort state
  1. Right-click the transaction that is in the Cannot Notify Abort state. This will display the superior MS DTC and subordinate transaction managers for the transaction.
  2. Having located the subordinate IBM LU6.2 transaction managers, force the transaction to abort on each of the IBM LU6.2 systems.
  3. Once you have manually aborted the transaction on all subordinate IBM LU6.2 systems, return to the MS DTC that shows the transaction in the Cannot Notify Abort state, and force that MS DTC to forget the transaction.

Caution Do not manually forget a transaction until all subordinate MS DTCs have been notified of the transaction outcome.

Resolving the Cannot Notify Commit State

The Cannot Notify Commit state indicates that the transaction has committed, but some subordinate MS DTC transaction managers or resource managers have not been notified of the transaction's outcome. You can manually resolve the transaction.

To resolve the Cannot Notify Commit State
  1. Right-click on the transaction that is in the Cannot Notify Commit state. This will display the superior and subordinate MS DTC transaction managers for the transaction.
  2. Having located the subordinate MS DTC transaction managers, force the transaction to commit on each subordinate system.
  3. Once you have manually committed the transaction on all subordinate systems, return to the MS DTC that shows the transaction in the Cannot Notify Commit state, and force that MS DTC to forget the transaction.

Caution Do not manually forget a transaction until all subordinate MS DTCs have been notified of the transaction outcome.


Resetting the MS DTC Log File

You should not reset the MS DTC log file under normal circumstances. Doing so will cause MS DTC to lose track of pending transactions, which may affect the consistency of the transaction-protected databases, message queues, and files coordinated by MS DTC. It is not necessary to reset the MS DTC log file to reclaim disk space within the file because MS DTC does this automatically.

You must reset the MS DTC log file to relocate it to another device or to change its size. Refer to changing the size or location procedures in Configuring the MS DTC Log File section if you wish to change log file attributes.

Before resetting the MS DTC log file, ensure that there are no transactions in the In Doubt, Cannot Notify Abort, or Cannot Notify Commit state.

For background information on the MS DTC log file, see Log File Management.

You cannot reset the MS DTC log file on a remote system. Because the Component Services administrative tool updates the MS DTC log file directly, it must run on the system where the log file resides.

To reset the MS DTC log file
  1. In the details pane of the Component Services administrative tool, right-click the computer containing the log file, and then click Properties
  2. In the computer properties dialog box, click the MSDTC tab.
  3. Under Service Control Status for MSDTC, click Stop to stop MS DTC.
  4. Under Log Information, click Reset Log to reinitialize the log file.

    If a log file already exists in the location specified by the drive and directory, clicking Reset Log deletes the current log file. Before deleting an existing log file, you must ensure that there are no transactions in the In Doubt, Cannot Notify Abort, or Cannot Notify Commit states. You can confirm the current transaction state using the Transaction List in Component Services administrative tool.

  5. Under Service Control Status, click Start to restart MS DTC.
  6. Click OK.


Monitoring MS DTC Performance

You can monitor the performance of MS DTC transactions using either the System Performance Monitor or the Component Services administrative tool. You would typically perform these tasks after you have set up transaction parameters (see Managing MS DTC).

Use the following links for step-by-step details.

  • Monitoring MS DTC Performance using the System Performance Monitor
  • Monitoring MS DTC Performance using the Component Services Administrative Tool
  • Viewing Event Messages


Monitoring MS DTC Performance using the System Performance Monitor

For in-depth MS DTC performance monitoring you should use the System Performance Monitor. It provides the most MS DTC performance information, and with it you can view and analyze performance information in a variety of ways.

To display MS DTC performance information using the System Performance Monitor
  1. Click Start, point to Programs, point to Administrative Tools, and then click Performance.
  2. In the details pane of Performance, right-click the chart, and then click Add Counters.
  3. In the Add Counters dialog box, in the Performance object box, select Distributed Transaction Coordinator.
  4. Under Select counters from list, select the MS DTC counters you want to display, and then click Add.
  5. When you are finished adding counters, click Close.

The following table describes meaning of the counters:

MS DTC Counter | Meaning
Aborted Transactions | Number of aborted transactions
Aborted Transactions/sec | Transactions aborted per second
Active Transactions | Number of currently active transactions
Active Transactions Maximum | Maximum number of transactions ever concurrently active
Committed Transactions | Number of committed transactions
Committed Transactions/sec | Transactions committed per second
Force Aborted Transactions | Number of transactions aborted by the system administrator
Force Committed Transactions | Number of transactions committed by the system administrator
In Doubt Transactions | Number of in-doubt transactions
Response Time – Average | Average time delta between transaction begin and commit
Response Time – Maximum | Maximum time delta between transaction begin and commit
Response Time – Minimum | Minimum time delta between transaction begin and commit
Transactions/sec | Transactions performed per second


Monitoring MS DTC Performance using the Component Services Administrative Tool

The Component Services administrative tool includes a Transaction Statistics window that displays statistical information about the transactions in which a server participated. You can use transaction statistics to get an overview of MS DTC performance.

To view transaction statistics
  • In the console tree of the Component Services administrative tool, double-click the computer for which you want to view transaction statistics, double-click Distributed Transaction Coordinator, and then click Transaction Statistics.

    You can view the states of your transactions under Current, Aggregate, and Response Times groups. For more information about transaction states, see MS DTC Transaction States.


Viewing Event Messages

For information on viewing event messages on Windows 2000, see the Event Viewer documentation included with the Component Services administrative tool. For Windows 2000, MS DTC events are recorded in the Windows Application event log.


Dealing with MS DTC Problems

Once of the most frequently reported errors for MS DTC is the "Failed to enlist" error. For example, the ODBC driver manager reports this error when a transactional component running in Component Services attempts to open a database connection and the driver manager cannot enlist the database connection in the current transaction. The ODBC driver manager enlists the database connection in the current transaction by calling the ODBC driver's SQLSetConnectionAttr (SQL_ATTR_ENLIST_IN_DTC) procedure. The ODBC driver manager displays the "Failed to enlist" message if the call to the SQLSetConnectionAttr procedure fails.

If this error occurs when your transactional component is accessing an Oracle database, refer to the "Failed to Enlist" document on the Internet at ftp://ftp.microsoft.com/bussys/viper/docs.

If this error occurs when your transactional component is accessing a Microsoft SQL Server database, please check the following.

  1. Verify that MS DTC Has Started.
  2. Verify Communication Between Two or More Computers.
  3. Configure the SQL Server to use TCP/IP Rather than Named Pipes.
  4. Check Transaction Timeout.


Verify that MS DTC Has Started

Make certain that MS DTC is "Started" on the system on which your components running in Component Services are deployed.

If your application is accessing a Microsoft SQL Server database on a remote system, ensure that MS DTC is "Started" on that system also. This is frequently the cause of the "Failed to Enlist Error."

For more information on starting and stopping MS DTC, see Starting and Stopping MS DTC.


Verify Communication Between Two or More Computers

When a transactional COM component on one system accesses a SQL Server database on another system, MS DTC propagates the MS DTC transaction from the first or "primary" system to the secondary system. Transaction propagation can only occur if the MS DTC process on the primary system can communicate with the MS DTC process on the secondary system. Actually, the MS DTC processes establish RPC connections in both directions, so a network configuration problem on either system can prevent the MS DTC processes from successfully communicating with one another. This will cause a "Failed to enlist error" to be returned by ODBC.

If a communication error occurs, the following MS DTC event may be recorded in the Windows 2000 Application event log.

MS DTC is unable to communicate with MS DTC on a remote system. MS DTC on the primary system established an RPC binding with MS DTC on the secondary system. However, the secondary system did not create the reverse RPC binding to the primary MS DTC system before the timeout period expired. Please ensure that there is network connectivity between the two systems.

This error indicates that MS DTC on your system was able to bind to MS DTC on your SQL Server system, but MS DTC on the SQL Server system could not perform the reverse bind to MS DTC on your system.

If your network configuration is incorrect, every attempt to connect to the remote SQL Server database will result in a "Failed to enlist" error. If you consistently get a "Failed to enlist" error even after MS DTC has been started on both systems, the most likely cause of the failure is a network configuration error.

To verify network communication between two computers
  1. Use Notepad to create a file called Pingtest.bat, and then paste the following batch file commands in it.
    echo off
REM Usage pingtest OtherMachineName
REM Must use a machine name and NOT an IP address
ping -n 1 %computername%
ping -n 1 %1
ipconfig /all
echo on

    The batch file uses %computername% to display the local IP address. It then displays the IP address of the remote machine you specify in the command line when executing the batch file. When you invoke the batch file, you must specify the name of the remote machine and not its IP address. Using the machine name forces Ping to resolve the machine name exactly as MS DTC does when it binds to the remote MS DTC machine.

  2. Run Pingtest.bat on your primary system to determine if you can "ping" your secondary system by name. Capture the output from the batch file in a text file. For example, if your primary system is machine "A" and your secondary system is machine "B," do the following:
    Pingtest B > AResults.txt
  3. Run Pingtest.bat on your secondary system to determine if you can "ping" your primary system by name. Capture the output from the batch file in a text file. For example, if your primary system is machine "A" and your secondary system is machine "B," do the following:
    Pingtest A > BResults.txt
  4. Examine the two resulting text files to ensure that the two machines can ping one another successfully.

If you use Hosts or Lmhosts files for TCP/IP name resolution, check these files very carefully to ensure that they contain valid computer name-to-IP address mappings. To do this, check the "Hosts" and the "Lmhosts" files in the %windir%>system32\drivers\etc\ directory on both the Component Services system and the SQL Server system. Frequently, the file on one system will be correct, while that on the other system is incorrect.

MS DTC runs under the identity of the System account by default. The MS DTC on one computer can communicate with the MS DTC on another computer only if the Guest accounts on both computers are enabled. If you disable the Guest account on either machine or in the Windows 2000 domain to which they belong, you must configure MS DTC to run under some other user name that can communicate with the remote computer.


Configure the SQL Server to Use TCP/IP Rather Than Named Pipes

If you see a "Failed to enlist" error only intermittently, then using Named Pipes rather than TCP/IP for SQL Server client-to-server communication may be the cause of the problem. Using Named Pipes for SQL Server client-to-server communication can result in intermittent "Failed to Enlist" errors. You should configure SQL Server to use TCP/IP rather than Named Pipes.

To configure SQL Server 6.5 to use TCP/IP
  1. Click the Start menu, point to Programs, point to Microsoft SQL Server 6.5, and then click SQL Client Configuration Utility.
  2. Click the Net Library tab.
  3. In the Default Network box, select TCP/IP Sockets.
  4. Click Done.

To configure SQL Server 7.0 to use TCP/IP
  1. Click the Start menu, point to Programs, point to Microsoft SQL Server 7.0, and then click Client Network Utility.
  2. Click the General tab.
  3. In the Default Network Library box, select TCP/IP.
  4. Click OK.


Check Transaction Timeout

If you see a "Failed to enlist" error, consider whether the component's transaction may have aborted due to transaction timeout before the database enlistment completed. You can increase the transaction timeout value through the Component Services administrative tool.

This is unlikely to be the problem unless your transactions are unusually long. However, it may be helpful to temporarily increase the timeout value to eliminate this as a potential source of trouble.

To check the transaction timeout period
  1. In the console tree of the Component Services administrative tool, right-click the computer where the transaction was initiated, and then click Properties.
  2. In the computer properties dialog box, click the MSDTC tab.
  3. Under Service Control Status for MS DTC, click Stop to stop MS DTC.
  4. On the Options tab, under Transaction Timeout, in the Transaction Timeout box, enter the value for the timeout period in seconds.

    You can specify any value between 0 and 4,294,967. A value of 0 specifies an infinite timeout period; this prevents transactions from ever timing out. You may need to experiment with different values to obtain the right timeout value for your system.

  5. Click OK.

The new setting will take effect after you stop and restart the COM+ application.


Obtaining MS DTC Support

This topic describes how to get support for troubleshooting MS DTC.

Using Oracle with MS DTC

For the latest support information on using an Oracle database with Component Services and MTS, refer to the "Oracle and MTS" document on the Internet at ftp.microsoft.com/bussys/viper/docs.

Submitting MS DTC Problem Reports

The following describes how to report MS DTC problems to the Microsoft Product Support organization.

Along with the problem report, please include the following information:

  • Specify the version number of the MS DTC software you are using.

    The MS DTC version number is displayed on the MSDTC tab of the Component Services administrative tool. Run the Component Services administrative tool on the system experiencing the error. Double-click Computers, right-click My Computer, and then click Properties. In the computer properties dialog box, click the MSDTC tab. The MS DTC version number is displayed near the bottom of the MSDTC tab.

  • If you have installed any Windows 2000 service packs, please check the version of each of the MS DTC files listed in Components of MS DTC. Windows 2000 Service Pack releases only include the .dll and .exe files that have changed since the initial product release.

    To check the version of the .dll and .exe files, use the Windows Explorer to locate each of the MS DTC .dll or .exe files in the System32 directory. Right-click the file, and then click Properties. In the Properties dialog box, click the Version tab. Note the File Version for each .dll or .exe listed in Components of MS DTC.

  • For MS DTC setup problems, include the Dtcinstall.log file located in the %windir% directory.
  • Report the complete text of any MS DTC error messages that are displayed, including any names or line numbers of source files.
  • Scan your Windows 2000 Application Event log and list any events originating from MS DTC near the time of the failure. Please include information from the Event Details tab and the Record Data tab.
  • Make a copy of the MS DTC log file so that Microsoft product support can examine it if needed. Your log file may be too large to submit with your problem report, but please retain the log file until the problem is resolved. The log file can normally be found at %windir%\System32\DTCLog\MSDTC.log.
  • Describe the circumstances leading up to the failure as completely as you can. If the application is distributed across two or more systems, please describe the application configuration and tell where the application components are running.
  • Describe which resource managers your application is using and provide the version number for each. Please list all of the databases, message queuing system, and other resource managers that are being used by the application.

    For example, if you were using an Oracle database, you might specify that you are using Oracle 7.3.5 or Oracle 8.1.0. If the resource managers are distributed across the systems in the network, describe where the resource managers are running. For example, it is important to know if your Microsoft SQL Server database is running on a remote Windows system or your Oracle database running on a Unix Solaris system.


Administering Queued Components

Queued Components, based on Message Queuing, is a Component Services feature that enables COM components to request services from another component even when that component is unavailable or offline. The requests are recorded, queued, and automatically played back at a later time when the component becomes available.

To enable queuing for a component that has been developed to support queuing, use the Component Services administrative tool to specify a COM+ application as queued. Add components to this queued application, and then start the Queued Components listener to make the application eligible to receive messages.

Use the following links to get background and task information.

Topic | Description
Queued Components Administration Concepts | Provides an overview of Queued Components concepts.
Queued Components Administration Tasks | Lists tasks for administering Queued Components.

Before You Go On

To use Queued Components, you must have Message Queuing installed on your computer.

Queued Components uses authenticated messages. Message Queuing requires that each user register a valid internal certificate to process authenticated messages. To register a Message Queuing internal certificate, see Obtaining a Message Queuing Internal Certificate.

For more information on developing queued components, see Queued Components in COM+ (Component Services), under Component Services in the Microsoft Platform SDK.


Queued Components Administration Concepts

A COM+ application can be marked as a queued application. Specifying an application to be queued creates a Message Queuing queue and associates it with this application. By default, this queue is transactional, which preserves the consistency and integrity of the data contained in the message — even if the message is unable to complete. After specifying a queued application, add components — either queueable or non-queueable — to the application.

Note If you prefer, you can add the components to a COM+ application first, then specify the application to be queued. The sequence of when an application is specified as queued does not matter. A component can be specified as queueable whether or not the application is queued. However, only queueable components in a queued application can be invoked asynchronously.

After specifying the queued application and adding the necessary components, you must enable the Queued Components listener. While specifying an application as queued allows it to receive messages, the application does not actively listen to or receive messages from the input queue until the Queued Components listener is started.

Any queueable components that are contained in the queued application can be executed asynchronously. Asynchronous execution means that you can start an operation at the server and continue processing while the server does the work you requested of it. In a synchronous environment, one component calls another component and must wait for the results of that call before handling another task. In the case of a queueable component, the call returns immediately — whether or not the processing has occurred. The component is free to move on to other tasks. Later, after the request has been processed, the requesting component receives notification of the result.

Occasionally a message cannot be processed for some reason, perhaps because of a problem with the server or queuing system. When a problem occurs, Queued Components retries the message several times before moving it to a final resting queue. Messages stay here until they are manually moved by using the Queued Components message mover utility. The message mover moves messages from one queue to another. Because the process of dequeuing a message must be accomplished by a trusted source, only users who have the role of QC Trusted User are able to use the message mover. For information on how to specify a role of QC Trusted User, see Assigning a User Account or Group to a Role.


Queued Components Administration Tasks

When administering queued components, your first task will be to specify the application as queued. After creating the queued application, you add components to the application. A queued application can contain both queueable or non-queueable components. There are, however, implications to mixing queueable and non-queueable components in the same application. If you intend to batch process work at a specific time during the day, you can use queued components to store the methods throughout the day and de-queue them at the predetermined time. Should this same application also contain non-queueable components, any call to the non-queueable component could unintentionally cause the queue to be processed — unless you specifically disable the listener by using the Component Services administrative tool. If you want to control when the queued methods are run, you must do one of the following:

  • Disable the listener by using the Listen checkbox in the Component Services administrative tool, or
  • Separate your queued and non-queued components into different applications.

Once you have created the queued application and added all the components for the application, your next step will be starting the Queued Components listener. When the Queued Components listener is started, the application begins reading messages from the input queue. To manually move messages from queue to queue or to retry a message that has landed on the final resting queue, you will be using the message mover.

Use the following links for step-by-step details.

  • Obtaining a Message Queuing Internal Certificate
  • Specifying an Application as Queued
  • Starting the Queued Components Listener
  • Using the Message Mover


Obtaining a Message Queuing Internal Certificate

You must obtain an internal Message Queuing certificate for each user so that the message can be authenticated when it is sent. If required by the receiving application, the digital signature is verified when the message is read from the queue to determine if the message came from the source claimed to have sent it.

To obtain a Message Queuing internal certificate

The following assumes that you are logged in as the user whose identity will be used to execute the COM+ application.

  1. In the Control Panel, open MS Message Queue.
  2. Select the Security tab.
  3. Click Renew Internal Certificate, then click OK.
  4. Click Close.


Specifying an Application as Queued

A queued application requires an associated Message Queuing queue. When you specify an application as queued, Component Services creates this queue. The queue is transactional and provides guaranteed delivery of the messages.

To specify an application as queued
  1. In the console tree of the Component Services administrative tool, right-click the COM+ application that you want to be queued, and then click Properties.
  2. On the Queuing tab, select the Queued check box.

    If the check box is unavailable, there are no components with queueable interfaces, and therefore the application can not be queued.

  3. Click OK.


Starting the Queued Components Listener

After establishing a queued application and its queued components, you can begin to invoke those components, causing request messages to be sent to the application's queue. To begin processing these queued requests, you must use Component Services to start a Queued Components listener.

Note The application must not be running when you start the Queued Components listener. If the application is running, it will not recognize the changed status of the Queued Components listener, and must be shut down and restarted before it will process the queued messages properly.

To start the Queued Components Listener
  1. In the console tree of the Component Services administrative tool, right-click the queued application, and then click Properties.
  2. On the Queuing tab, select the Listen check box.
  3. Click OK.


Using the Message Mover

Occasionally a situation occurs in which a message cannot be successfully delivered to its intended destination, usually because of a problem with the system or configuration. You may receive event long entries that indicate there are messages that cannot complete. To verify this, use Message Queuing to view the status of the queues. Some queuing problems are easily solved. For example, if the server was offline for some reason, you can bring the server back online. Once you resolve the problem, use the Queued Components message mover to re-queue the message. The message mover is a tool that moves all failed messages from one queue to another so that they can be retried.

The message mover is an Automation object that can be invoked with a simple script, such as the following example of VBScript:

Dim OMessageMover as IMessageMover
Dim BatchSize
Dim MovedMessage

setIMessageMover = CreateObject("QC.MessageMover")
OMessageMover.put_SourcePath = "Source Queue path name"
OMessageMover.put_DestPath = "Destination Queue path name"
OMessageMover.put_CommitBatchSize = BatchSize ' number of messages you want to move as a batch
MovedMessage = OMessageMover.MoveMessage


COM+ Glossary

activation
The chain of events that results in the creation of a COM object and the return of a valid pointer to an interface on that object. COM+ services rely on appropriate activation of an object based on the object's configuration. In the course of activation, the system determines the context in which the object runs, initializes the context properties, checks access permissions, and establishes a security identity. See also Just-in-time (JIT) Activation and activation type.

activation type
Category for a COM+ application that indicates whether the application runs in or out of its client's process space, determining how it can use role-based security and whether it supports remote access or queuing. See also COM+ library application and COM+ server application.

activity
For queued components, an activity is a logical thread comprised of one or more transactions and containing a collection of components that are grouped into a COM+ application.

application proxy
A set of files containing registration information that allows a client to remotely access a COM+ server application. When run on a client computer, an application proxy file writes information about the server application — including CLSIDs, ProgIDs, RemoteServerName, and marshaling information — to the client computer. The client can then remotely access the server application.

COM+ (Component Services)
A set of services based on extensions of Microsoft Transaction Server (MTS) and the Component Object Model (COM) that provides improved threading and security, transaction management, object pooling, queued components, and application administration and packaging.

COM+ application
One or more COM components that have been configured as a unit to use one or more of the COM+ (Component Services), provided by Windows 2000.

COM+ catalog
A system data store that contains configuration information for COM+ applications on a given server computer. Settings made with the Component Services administrative tool are written to the COM+ catalog.

COM+ library application
A COM+ application that runs in the process of the client that creates it. Library applications can use role-based security, but do not support remote access, or queued components.

COM+ server application
A COM+ application that runs in its own process. Server applications can support all COM+ services.

Component Services administrative tool
A Windows 2000 Microsoft Management Console snap-in through which administrators and developers can create, configure, and maintain COM+ applications, and administer distributed transactions and memory-resident databases. Through this tool, you can also view system events and manage system services local to the computer on which the tool is installed.

Compensating Resource Manager (CRM)
Compensating Resource Managers (CRMs) enable non-transactional resources to participate in a two-phase commit transaction with the Microsoft Distributed Transaction Coordinator (DTC) by using a compensating action to reverse the original work. Typically CRMs do not provide the isolation capabilities of full resource managers, but they do provide transactional atomicity and durability by writing to a log.

context
A set of properties associated with one or more COM objects that are used to provide services for those objects. Every COM object runs in a single context from activation to deactivation (always within the same apartment). Initialized when an object is activated, context properties are based on context properties the object's client and the object's configuration.

configured component
A COM component that has been installed into a COM+ application. Once installed the component is configured within the COM+ catalog to make use of the available Component Services, including transactions, role-based security, queued components, events, and object pooling.

Just-In-Time (JIT) activation
A mechanism in which a COM object is activated only when needed to process requests from clients. Objects can be deactivated even while clients hold references to them, allowing otherwise idle server resources to be used more productively.

listener
With queued components, a COM object that opens the message queue associated with its host application and waits for messages to arrive. As messages arrive, the listener dispatches threads that process messages.

message mover
With queued components, a tool that will move failed messages back to their input queue so that they can be retried. The message mover moves messages transactionally, so messages are not lost or duplicated in the event of failure during the move.

.msi file
A file created by the Component Services administrative tool when you export a COM+ application or application proxy for installation on another computer. The .msi file can be installed on any Windows-based client using Windows Installer.

neutral apartment (NA) model
A neutral apartment supports execution of its objects on any thread type and is the recommended threading model for COM components and COM+ applications.

object pooling
A COM+ service that creates and maintains a group of class instances so that clients requesting services from an object can receive a pointer to a running object immediately rather than wait for the system to create the object. Object pooling can greatly increase performance of your application when a given object is expensive to create, such as objects that require connections to databases.

Phase Zero notification interfaces
Interfaces that allow applications to detect when a transaction is ready to proceed with a two-phase commit (2PC) protocol, so that they can perform such operations and communicate to the Transaction Manager when they have been completed.

player
With queued components, the player retrieves the message from the queue, loads the server object and the standard interface stubs to unmarshal data and invoke server methods.

queued components
A COM+ service through which COM components can make calls to another component whether or not that component is available to receive them. The requests are recorded, queued, and automatically played back at a later time when the component becomes available. Queued Components is based on Message Queuing.

recorder
With queued components, the recorder is a system-provided DLL that serves as a proxy manager for the server object and selects queuable interfaces from the COM+ catalog.

resource dispenser
A resource dispenser manages nondurable shared state on behalf of the application components within a process. Resource dispensers are similar to resource managers, but without the guarantee of durability.

resource manager
A system service that manages durable data. COM+ server applications use resource managers to maintain the durable state of the application, such as the record of inventory on hand, pending orders, and accounts receivable. Resource managers work in cooperation with the Microsoft Distributed Transaction Coordinator to guarantee atomicity and isolation to an application.

role-based security
A COM+ security service provided for COM+ applications. A role represents a category of users defined for a COM+ application for the purpose of determining access permissions to the application's resources. Roles are assigned by a developer to components, interfaces, and methods. Users are assigned by an administrator to appropriate roles, enabling a user within a given role to access any resources to that role is assigned.

shared property manager
A tool that provides synchronized access to application-defined, process-wide properties (variables).

state
Condition defining whether or not an object maintains instance-specific data in internal variables between method calls.

Transaction Internet Protocol (TIP)
Transaction Internet Protocol is a standard two-phase commit protocol that enables heterogeneous transaction managers to coordinate distributed transactions, especially over the Internet.

The TIP two-phase commit protocol is simple to implement and is independent of the application-to-application communications protocol, such that it may be used with any application protocol but especially HTTP.

unconfigured component
A COM component that has not been installed into a COM+ application.

XA Interfaces
Interfaces that allow MTS application developers to access XA-compliant databases and create resource managers that operate with relational databases, message queuing, transactional files, and object-oriented databases. Although Microsoft does not directly support the XA protocol, Microsoft does support translation facilities between OLE transactions and XA.


Browsing the User Database

You would browse the user database in the Component Services administrative tool when you need to find a fully qualified user or group name. For instance, you can browse the user database to locate a user for whom you want to grant access permissions.

To browse the user database
  1. In the Add Users and Groups dialog box, in the List Names From box, select the domain containing the user or group you want to add.
  2. To see the users that belong to the selected domain, click Show Users.
  3. To see the members of a particular group, select the group in the Names list and click Members.
  4. If you cannot locate the user or group you want to add, click Search.
  5. In the Find Account dialog box, select the domain you want to search (or click Search All), type the name you want to look for in the Find User or Group box, and then click Search.

    When located, the fully qualified name of the user or group will appear in the Search Results box.

  6. When the Search Results box contains the names you want to add, click Add.