Microsoft Transaction Server Release Notes

Microsoft Transaction Server Release Notes

This document contains late-breaking information for Microsoft® Transaction Server (MTS). For further information, see the following topics in Personal Web Server, Help: Setting Up Microsoft Transaction Server What’s New in MTS 2.0? MTS Product Documentation

Late-Breaking Information and Known Limitations

The following sections contain late-breaking information that is not covered in the regular documentation, as well as known bugs and limitations.

Setting System Package Identity

When installing MTS, set the System package identity before creating any new packages as follows:

1. Create a new local Windows NT

   Ò

   group named “MTS Administrators” and a new local user named “MTS Administrator”.

2. Add the “MTS Administrator” user to the “MTS Administrators” and “Administrators” groups.
3. Set the identity of the System package to “MTS Administrator”.
4. Shut down the System package so that it will be restarted with the new identity.

User Rights for MTS Packages

Make sure the user account for the identities of the System package and other MTS packages have the Windows NT “Log on as a service” user right. You can verify this by using the Windows NT User Manager:

1. From the Policies menu, choose User Rights.
2. Click Show Advanced User Rights.

Setting Up MTS to Access Oracle Databases

This information entirely replaces earlier documentation that described how to use Oracle with Microsoft Transaction Server, including that in the Microsoft Transaction Server 2.0 online Help documentation.

You can enable transactional MTS components to access an Oracle 7.3.3 database through ODBC. MTS works with Oracle 7 Workgroup Server for Windows NT, Oracle 7 Enterprise Server for Windows NT, Oracle 7 Enterprise Servers on UNIX, and Oracle Parallel Server on UNIX.

Your MTS component may access an Oracle 8 database on either Windows NT or Unix provided your Microsoft Transaction Server component uses the Oracle 7.3.3 client software. MTS does not support Oracle 8 client software.

This section includes the following topics:

• Required Software
• Setting Up Oracle Support
• Testing Installation and Configuration of MTS Support for Oracle
• Validating Oracle Installation and Configuration Using the Sample Bank Application
• Administering Oracle and Microsoft Distributed Transaction Coordinator
• Known Limitations of MTS Support for Oracle

Required Software

The following software is required to access an Oracle database from MTS components.

Component	Version
Oracle Database on Windows NT	7.3.3 (with patch 4 or later)
Oracle Database on UNIX	7.3.3 (with patches)
Oracle SQL*Net	2.3.3 (with patch 2.3.3.0.3 or later)
Oracle OCIW32.DLL	1.0.0.5 or later
Oracle SQLLIB18.DLL	1.8.3.0.1 or later
Oracle XA73.LIB	7.3.3.2.0 or later
Microsoft Transaction Server 2.0	2.0
Microsoft ODBC Driver for Oracle (MSORCL32.DLL)	02.73.7283.1 or later
ActiveX Data Objects (ADO)	1.5

Important Note: Earlier versions of the software will not work properly. Please ensure you install these or later versions of the software. Failing to do this is by far the most common source of problems when trying to use Microsoft Transaction Server with Oracle.

Oracle Database on Windows NT

If your Oracle database resides on Windows NT, you may install either the Oracle 7.3.3 Workgroup Server release for Windows NT or the Oracle 7.3.3 Enterprise Server release for Windows NT. The Oracle 7.3.2 and earlier releases of Oracle for Windows NT are not supported and will not work in conjunction with MTS transactions.

You must install the Oracle 7.3.3 patch release that is listed in the table above. The Oracle 7.3.3 release will not work with MTS unless this patch release is installed.

You must submit a problem report to the Oracle Customer Support Organization to obtain the Oracle patch release. This patch release was not available from the Oracle public web site at the time this note was written.

You may install Oracle 8 on Windows NT provided your Microsoft Transaction Server components use Oracle 7.3.3 client software. MTS does not support Oracle 8 client software.

Oracle Database on UNIX

If your Oracle database resides on UNIX, you must install the Oracle 7.3.3 release (or later) for that UNIX platform. In most cases, you will also be required to install an Oracle 7.3.3 patch release for Oracle on UNIX.

You must check with Oracle Customer Support to determine if an Oracle 7.3.3 patch release is required for your UNIX platform. Explain that you are going to access your Oracle database on UNIX using the new XA transaction support that is now included in the Oracle 7.3.3 release on Windows NT.

The following patch releases are known to work:

Platform	Oracle Patch
HP 9000	7.3.3.3
IBM AIX	7.3.3.2
Sun Solaris	7.3.3.2

You may install Oracle 8 on Unix provided your Microsoft Transaction Server components use Oracle 7.3.3 client software. MTS does not support Oracle 8 client software.

Oracle Clients on Windows NT or Windows 98

If your Microsoft Transaction Server components access an Oracle database on a remote Windows NT or Unix system, ensure that the following Oracle client software is present on your Microsoft Transaction Server system. Ensure that the client software is at the proper version level. The table at the beginning of the Required Software section specifies which versions are needed.

Component

Oracle SQL*Net

Oracle OCIW32.DLL

Oracle SQLLIB18.DLL

Oracle XA73.LIB

 

Oracle SQL*Net

You must install the specified version of Oracle SQL*Net on your Microsoft Transaction Server system.

Oracle OCIW32.DLL

You must install the specified version of Oracle OCIW32.DLL on your Microsoft Transaction Server system.

The following version of the Oracle OCIW32.DLL is known to work:

Version 1, 0, 0, 5 Tuesday, March 18, 1997 2:47:52 PM Size 18KB. 

The following version of the Oracle OCIW32.DLL is known to fail:

Version 7.x Thursday, February 01, 1996 12:50:06 AM Size 36 KB

We obtained the correct version of this DLL from the Oracle 7.3.3 installation CD from the \WIN32\V7\RSF73 directory.

Oracle SQLLIB18.DLL

You must install the specified version of Oracle SQLLIB18.DLL on your Microsoft Transaction Server system.

Oracle XA73.LIB

You must install the specified version of Oracle XA73.LIB on your Microsoft Transaction Server system.

Microsoft Transaction Server 2.0

You must install Microsoft Transaction Server 2.0 if you wish to access an Oracle database using Microsoft Transaction Server under transaction control.

Microsoft ODBC Driver for Oracle

The Microsoft ODBC Driver 2.0 for Oracle (MSORCL32.DLL) version 02.73.7283.1 or later is required. The Windows NT 4.0 Option Pack program automatically installs this DLL.

If you wish to access an Oracle database, we strongly suggest that you use the new Oracle 2.0 driver even if you do not require transaction support. This new driver offers better performance than the Oracle 1.0 driver it replaced The Oracle 1.0 driver serialized all activity at the driver level; requests were single-threaded through the driver. The Oracle 2.0 driver serializes all activities at the connection level. This allows different database connections to be used in parallel.

ActiveX Data Objects (ADO)

If your applications use ADO, you must install the ADO version 1.5. Earlier ADO releases will not work with the new ODBC 3.5 Driver Manager. ADO 1.5 is included in the Windows NT 4.0 Option Pack.

Setting up Oracle Support

To set up Oracle support for MTS transactional components

1. Install the Oracle 7.3.3 release on your Oracle database server system.

   If your Oracle database is located on a Windows NT system, install the Oracle 7.3.3 release on Windows NT.

   If your Oracle database is located on a UNIX system, install the Oracle 7.3.3 release on that system.

   Ensure that the correct version of the Oracle OCIW32.DLL is installed as described in the Required Software section.

2. Install the required Oracle 7.3.3 patch release on your Oracle database server system.

   If your Oracle database is located on a Windows NT system, install the Oracle 7.3.3 patch release that is listed in the Required Software section.

   If your Oracle database is located on a UNIX system, install the Oracle 7.3.3 patch release that is required for your version of UNIX.

3. Install Oracle 7.3.3 Client software.
4. If your Microsoft Transaction Server components access an Oracle database on a remote Windows NT or Unix system, ensure that the correct Oracle client software is present on your Microsoft Transaction Server system.

   Install the specified Oracle patch release on your Microsoft Transaction Server system and ensure that the client software matches the version levels listed in the table in the Required Software section.

5. Install Microsoft Transaction Server 2.0

   When you install Microsoft Transaction Server 2.0, the following software will be installed.

   • Microsoft Transaction Server 2.0, including the Microsoft OCI Interface
   • Microsoft ODBC 3.5 Driver Manager
   • Microsoft ODBC Driver for Oracle
   • ADO 1.5
6. Delete the DTCXATM.LOG.

   If you have never installed the Microsoft Transaction Server 2.0 Beta release, skip this step.

   If you previously installed the Microsoft Transaction Server 2.0 Beta release, use the Windows Explorer to determine if the DTCXATM.LOG file is present on your system. If so, stop the Microsoft DTC service and delete the DTCXATM.LOG file.

   You should only delete the DTCXATM.LOG file once when you first upgrade from the Microsoft Transaction Server 2.0 beta release. You should never delete the DTCXATM.LOG file thereafter, because it may contain vital recovery information.

7. Enable Oracle XA Support

   Perform the following steps to enable Oracle XA transaction support:

   1. The Oracle system administrator must create views known as V$XATRANS$. To do this, the administrator must run an Oracle-supplied script, named “xaview.sql”. This file can usually be found in C:\ORANT\RDBMS73\ADMIN.
   2. The Oracle system administrator must grant SELECT access to the public on these views.

      Grant Select on V$XATRANS$ to public.

   3. In the Oracle Instance Manager, click Advanced Mode on the View menu and select Initialization Parameters in the left pane. In the right pane, select Advanced Tuning and increase the “distributed_transactions” parameter to allow more concurrent MTS transactions to update the database at a single time.

   Consult your Oracle Server documentation for more information about configuring Oracle XA transaction support.

8. Configure Integrated Security

   Oracle databases have integrated security that uses Windows NT authentication to validate database users. This allows a user to log on to Oracle without supplying a separate user account or password. Users can maintain one user account and password for both Windows NT and Oracle.

   If your MTS components always supply a user account and password when connecting to Oracle databases, then you are not using integrated security. This is true whether your applications specify the user account and password directly or indirectly through an ODBC DSN. In either event, you are not using integrated security and can ignore this step.

   If you use integrated security, you must configure MS DTC to run under a user name and password authorized to connect to your Oracle database. This is required because during database recovery, MS DTC opens your Oracle database to report the outcome of in-doubt transactions. See “Changing the User Account Under Which Microsoft Distributed Transaction Coordinator Runs” below. Use the Oracle security administration tools to ensure that the user name you specify is authorized to open your Oracle database.

   For more information on Oracle’s integrated Windows NT security facilities, consult your Oracle documentation.

9. Configure Oracle to support more connections

   If you want to create more than a few dozen connections to an Oracle database, you must configure the Oracle server to support additional database connections. See “Configuring Oracle to Support a Large Number of Connections” below for more information.

Testing Installation and Configuration of MTS Support for Oracle

After installing and configuring Oracle support, you must validate your Oracle installation using the Oracle test program installed with MTS. The Oracle test program uses Oracle’s OCI XA interfaces in much the same way that MTS uses them.

The Oracle test program determines whether you can connect to an Oracle database using Oracle’s XA facility. The Oracle test program uses standard Oracle interfaces and transaction facilities. It makes no use of Microsoft Transaction Server or Microsoft Distributed Transaction Coordinator. Therefore, failure of the test program indicates that your Oracle system is improperly installed or configured. If the Oracle test program fails, reinstall and reconfigure Oracle, or contact the Oracle Support Organization for assistance

To run the Oracle test program

1. Verify that you have installed all of the correct versions of the software as described in Required Software.
2. Create an ODBC DSN that refers to your Oracle database. Ensure that your DSN uses the new Microsoft Oracle ODBC 2.0 driver.
3. Ensure that you have enabled Oracle XA support.

   Delete all existing Oracle trace files from the machine containing the MTS components that access the Oracle database. The easiest way to do this is to use the Windows Explorer to locate and delete all *.TRC files.

   If the Oracle test program fails, the trace files may help you determine the source of the problem. By deleting all obsolete trace files, you make it easier to find any newly created ones.

4. If you previously installed the Microsoft Transaction Server 2.0 beta release, use the Windows Explorer to determine if the DTCXATM.LOG file is present on your system. If so, stop the Microsoft DTC service and delete the DTCXATM.LOG file.

   If you have never installed the Microsoft Transaction Server 2.0 beta release, you can skip this step.

   You should only delete the DTCXATM.LOG file once when you first upgrade from the Microsoft Transaction Server 2.0 beta release. You should never delete the DTCXATM.LOG file thereafter, because it may contain vital recovery information.

5. From the MS-DOS Command prompt run the Oracle test program (TestOracleXaConfig.exe) and supply your Oracle server user ID, password, and service_name. For example:

   c:>TestOracleXaConfig.exe -U -P -S.

   If you run the test program with no parameters, the program will display help information that describes the required parameters.

   The test program will display information about each Oracle operation it performs and will indicate whether each operation was successful.

6. If the Oracle test program is able to connect to your Oracle database server without error, then it is very likely that MTS will work with Oracle also. If the Oracle test program reports any errors, follow these steps:
   • Document the exact error message that the Oracle test program displays.
   • Examine the Oracle trace file produced when running the Oracle test program. The Oracle trace information is located in the *.TRC file. The Oracle trace file contains extended error information that is extremely helpful in diagnosing problems.
   • Contact your Oracle support representative for assistance.

Validating Oracle Installation and Configuration Using the Sample Bank Application

After you have validated your Oracle installation and configuration using the Oracle test program, you should use the Sample Bank Application supplied with Microsoft Transaction Server to ensure that Microsoft Transaction Server can access your Oracle database.

To validate Oracle support using Sample Bank

1. Ensure that you have verified that your Oracle system is installed and configured correctly using the Oracle test program provided by MTS. If the Oracle test programs reports any error, you must correct that problem before proceeding.
2. On the Oracle database server, create a table named “Account”. The following example demonstrates how to set up the Account table.

   Owner scott

   Name of Table Account

   Column 1 Name AccountNo of type NUMBER

   Column 2 Name Balance of type NUMBER

3. Populate the table with at least two rows. The following table illustrates how to populate the table.

   AccountNo Balance

   1 1000

   2 1000

4. Create a file DSN using the ODBC configuration utility. Name the file DSN “MTSSamples”. Then manually update the DSN file to add the user’s password. The following example demonstrates how to add the user’s password to a file DSN. [ODBC]

   DRIVER=Microsoft ODBC for Oracle

   UID=scott

   PWD=mypassword

   ConnectString=myserver

   SERVER=myserver

5. Save the file DSN and run the Sample Bank client.

Administering Oracle and Microsoft Distributed Transaction Coordinator DLL Name Changes in Future Releases of Oracle

Oracle sometimes changes DLL names when they release new versions of their product. Microsoft Transaction Server relies upon knowing the names of some Oracle DLLs. MTS currently looks for the DLL names provided with the Oracle 7.3.3 release. If Oracle renames these DLLs, you must modify the values of the following registry keys:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Transaction Server\Local Computer\My Computer

Under this key there are two string-named values.

• OracleXaLib “xa73.dll”
• OracleSqlLib “sqllib18.dll”

Changing the User Account under Which Microsoft Distributed Transaction Coordinator Runs

If you configure the MicrosoftÒ Distributed Transaction Coordinator (MS DTC) to run under an account other than the System account, you must specify an account that is a member of the Administrators group. If not, MS DTC may fail to start, and you will see the following message in the Windows NT event log.

XATM log object failed to set log encryption key

You can configure the user ID for MS DTC as follows:

1. Stop MS DTC.
2. From the Start menu select Settings and then Control Panel.
3. Double-click the Services icon in the control panel.
4. Double click on MS DTC in the Service list box.
5. Select Log On As and specify a user name and password.
6. Restart MS DTC.

Configuring Oracle to Support a Large Number of Connections

If you want to create more than a few dozen connections to an Oracle database, you must configure the Oracle server to support additional database connections.

You may experience one or more of the following errors if you fail to do this:

• Failures on SQLConnect calls.
• Failures to enlist on the calling object’s transaction, which may result in any of the following errors in the Oracle trace file:
  • Too many sessions
  • TNS server failed to locate the server name
  • Too many distributed transactions
• Timeouts while waiting for database locks. This is likely to occur if the configured number of locks is insufficient for the number of concurrently active transactions.
• Record collision due to locks held by in-doubt transactions.

If you experience any of these problems, consider increasing the following Oracle server configuration parameters:

• sessions
• distributed_lock_timeout
• distributed_transactions
• dml_locks
• max_transaction_branches
• open_cursors
• processes
• queuesize

Sessions

The value for sessions should typically be three times the total number of database connections that you expect your applications to make.

Queuesize

If the queue size for the Oracle Listener process is inadequate, the Listener sometimes falls behind and rejects database open requests. This happens if the Oracle Listener receives too many connection requests and its queue overflows. A client that encounters this error reportsthe error message ‘ORA-12541: No Listener’ and the client log or trace fileswill show the ECONREFUSED message.

To correct this problem:

1. Stop the Oracle listener on the system containing the Oracle database server.
2. Increase the QUEUESIZE parameter in the LISTENER.ORA, TNSNET.ORA, or NAMES.ORA files on the Oracle database server system. Choose the queue size based on the number of simultaneous, or nearly simultaneous, connection requests you anticipate.

   We suggest that you select a generous value for QUEUESIZE because the Oracle system typically opens more than one database connection for each transactional database connection that your application opens. As a result, the Oracle listener queue may become full and overflow.

   To accommodate 100 requests, change the LISTENER.ORA file as follows:

   QUEUESIZE = 100

3. Restart the Oracle listener.

Known Limitations of MTS Support for Oracle ADO 1.5 Release Is Required When Using ODBC 3.5

If your applications use ADO, make certain that you install ADO 1.5. Refer to the Required Software section for more information.

No Oracle Support on Digital Alpha Platform

Oracle database connectivity is not supported for Microsoft Transaction Server components running on the Digital Alpha platform. Support for Oracle on the Digital Alpha platform will be added in a future release.

Oracle OCIW32.DLL Version Problem

It is important that the correct version of the OCIW32.DLL is installed on your computer. You should check the version of this DLL any time you reinstall Oracle or Microsoft Transaction Server.

No Oracle Access from MSCS (Wolfpack) Clusters

Microsoft Transaction Server applications that reside on MSCS (Wolfpack) clusters cannot access XA databases, including Oracle databases. This is the result of a limitation in Microsoft Distributed Transaction Coordinator.

Currently, Microsoft Distributed Transaction Coordinator stores encryption information related to XA recovery in the Windows NT registry. This information cannot currently be replicated between the two nodes in an MSCS cluster. As a result, Microsoft DTC cannot be used with any XA-compliant database in clustered environment. We intend to eliminate this restriction in a future release.

Security and Communication Between Remote MS DTC Computers

If your application performs transactions spanning two or more computers, you must ensure that the MS DTCs on these computers are configured to communicate with each other. 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 NT domain to which they belong, you must configure MS DTC to run under some other user name that can communicate with the remote computer. See “Changing the User Account Under Which Microsoft Distributed Transaction Coordinator Runs” above.

MS DTC with MSCS Requires QFE

Customers who use MS DTC in an MSCS environment should install Windows NT QFE Q116844. This QFE fixes a Remote Procedure Call (RPC) problem that can cause an MS DTC client to hang when attempting to connect to MS DTC on a clustered server. This fix is also part of Windows NT QFE1, available at the Windows NT Option Pack Web download site.

Remote Server Name Must Specify a Virtual Server on MSCS Servers

Clustered servers must set the Remote Server Name property to a virtual server name using the MTS Explorer. This enables remote clients to access MTS components within the cluster, and, in the event of failure, ensures that clients are referencing the cluster, not a specific node within that cluster.

MTS Package Identities Must Be in Administrator Group on MSCS Clusters

For MTS packages on MSCS clusters, the user account associated with the package identity must be a system administrator or must have Full Control cluster access permissions (as set in cluadmin). If you do not run the package under the identity of a system administrator, MTS will be unable to connect to MS DTC.

MTS on MSCS Clusters Requires Same Windows NT Directory Path on All Nodes

MTS requires that both the Windows NT directory have the same path on all nodes within an MSCS cluster (for example, c:\winnt).

Shut Down MSCS Cluster Resources Before Installing MTS

You must shut down all MSCS cluster resources (such as SQL Server) that are affected by MTS setup prior to running the MTS setup program.

Installing SQL Server 6.5 After Installing MTS

You can install SQL Server 6.5 after installing MTS. It is recommended that you install SQL Server 6.5 before installing MTS. If you install SQL Server 6.5 after installing MTS, MTS Setup will attempt to ensure that MS DTC works properly.

Run the INSTCAT.SQL Script

As a convenience, MTS includes the INSTCAT.SQL script. This script updates the catalog stored procedures for the SQL Server ODBC driver. If you have not done so already, run this script using the SQL Server isql utility.

Documentation Errata on Security

Security authorization is not enabled by default.

You cannot set a package’s identity to a group.

When setting package identity, MTS validates the password that you enter. However, if you change the password for the account without updating the password in the MTS Explorer, the package cannot run.

MS DTC Log File Can Be Compressed

The MS DTC log file can now be located in a compressed directory. However, for optimum performance, do not compress the Microsoft DTC log file or store it in a compressed directory. MS DTC must decompress the log file before it can be used.

Problems Resetting the MS DTC Log File on Windows 98

When resetting the MS DTC log file on Microsoft Windows 98, you may see a dialog box labeled “MTxOCI” followed by a second dialog box labeled “”Failed to create the MS DTC log file.” If this occurs, you must disable automatic startup of MS DTC as described in “Monitoring MTS Transactions on Windows 98.” Restart your computer and reset the log file. You can then re-enable automatic startup of MS DTC.

Other problems resetting the MS DTC log file can be fixed by closing the MTS Explorer, restarting MTS Explorer, and attempting the reset again. In some instances, this may take several tries before succeeding.

Monitoring MTS Transactions on Windows 98

The documentation for starting and stopping MS DTC on MicrosoftÒ WindowsÒ 98 should read as follows:

By default, the Microsoft Distributed Transaction Coordinator (MS DTC) is configured to start automatically when a Windows NT or Windows 98 system starts. To prevent MS DTC from automatically starting after rebooting a Windows 98 computer, use the registry editor to find the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunServices registry key and then delete the value entry named MSDTC. If you want to enable automatic startup of MS DTC again, use the registry editor to create a value entry named MSDTC with the string value “msdtcw -start" under the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunServices registry key.

Note that the name of the service is “msdtcw", not “msdtc", and that there is a space before the hyphen.

No Remote Administration of MTS 2.0 Computers from MTS 1.x Computers

You cannot remotely administer an MTS 2.0 installation from a computer running a previous version of MTS. Attempting to do so will return an error code or cause the MTS Explorer to terminate unexpectedly.

No Individual Package Shutdown when Remotely Administering an MTS 1.x Computer

Individual package shutdown is not supported when remotely administering an MTS 1.x computer.

Visual Basic 5.0 Shutdown with MTS 2.0

After installing MTS 2.0, you may see an Access Violation when shutting down MicrosoftÒ Visual BasicÒ 5.0. This is a known Visual Basic 5.0 bug that can be fixed by installing Visual StudioÔ Service Pack 2 from http://www.microsoft.com/vstudio. Refer to Knowledge Base article Q167213 for more information about this problem.

Multiple Server Processes on Windows 98

There is a known problem that occurs when, if an MTS server process terminates unexpectedly (because of a failfast, an assert, or an access violation), subsequent attempts to restart the application create multiple MTS processes. (The correct behavior should be only one MTS process per package.) In case of unexpected server process termination, you must reboot your Windows 98 computer.

Deadlocks on Windows 98 When Using Named Pipes

There is a known problem that may cause deadlocks when using more than approximately 40 Named Pipe connections from a Windows 98 client to MS Distributed Transaction Coordinator (DTC). To fix this problem, change the protocol between the ODBC driver and SQL Server to TCP/IP.

Components and TreatAs and AutoTreatAs Registry Keys

COM allows one server to emulate another using the TreatAs or AutoTreatAs registry keys. Suppose a client creates a component of a given CLSID using CoCreateInstance. If the TreatAs or AutoTreatAs key is present under that CLSID in the registry, COM will instead create the component indicated by this key. This effectively routes client requests to the emulating server. (The same routing is possible using the ProgID if the client refers to its servers by ProgID instead of CLSID.)

Components being emulated using TreatAs or AutoTreatAs are not valid MTS components and cannot be imported. If the emulation is to be added after the component is imported, the component must be deleted from the MTS catalog, then replaced with the emulating component.

Mixed Threading Models in a Server Process

Within a server process, objects in the same activity must be registered with compatible threading models. The following combinations are valid:

• Any combination of apartment, both, or free
• Single-threaded only

Note that this means that single-threaded MTS components cannot be created by an Active Server Page running in-process with IIS or in-process with an IIS application using process isolation.

Do Not Create Non-MTS Local Servers Using CreateInstance

Creating non-MTS local servers using the context object’s CreateInstance method is strongly discouraged. Such servers will not scale well and may result in additional server instances that are not shut down by MTS. If you need to create a non-MTS local server, use CoCreateInstance.

Do not use COM surrogates within MTS. Instead, load in-process servers into MTS server processes.

MTS Security Does Not Work With IIS Impersonation

MTS role-based package access control does not work properly when packages are front-ended by mutliplexers that impersonate multiple clients (for example, Internet Information Server). MTS packages used in these environments should be configured with security disabled.

This can be fixed by installing Windows NT QFE1, available at the Windows NT Option Pack Web download site. After installing this QFE, role-based security will work properly with IIS.

When you create secure IIS applications that use process isolation, IIS creates an MTS package that is set to run as IWAM_. If you wish to change the identity of these packages, you should also add the new package identity to the “MTS Trusted Impersonators” group or security will not work properly in other out-of-process MTS components called by your package. If this is not done, the caller will appear to be IWAM_ rather than the actual client of IIS.

Using ErrorInfo with ADO

ADO erases any information that you might have put in the ErrorInfo object. There is a code work-around for this problem that needs to be implemented in your error handler.

For Visual Basic, the code is similar to the following:

ErrorHandler: ' cleanup If Not adoRS Is Nothing Then Set adoRS = Nothing End If If Not adoConn Is Nothing Then Set adoConn = Nothing End If Err.Raise Err.Number, "Bank.Accout.Post", Err.Description Exit Function

For Visual C++, the code is similar to the following:

// // ErrorInfo is saved here because the following // ADO cleanup code may clear it. // IErrorInfo * pErrorInfo = NULL; GetErrorInfo(NULL, &pErrorInfo); if (adoRsBalance) adoRsBalance->Release(); if (adoCoConnection) adoCoConnection->Release(); AtlReportError( CLSID_CAccount, pErrMsg, IID_IAccount, hr); // // put the error back in TLS // SetErrorInfo(NULL, pErrorInfo);

For Visual J++, the code is similar to the following:

if (adoRsBalance != null) { if (adoRsBalance.getState() == ObjectStateEnum.adStateOpen) adoRsBalance.Close(); ComLib.release (adoRsBalance); } if (adoConn != null) { if (adoConn.getState() == ObjectStateEnum.adStateOpen) adoConn.Close(); ComLib.release (adoConn); }

Note In Java you must explicitly close recordsets and/or connections as well as explicitly release the ADO objects.

No Sample Bank ASP Client

The documentation incorrectly states that an Active Server Page (ASP) version of the Sample Bank client is provided.

Maximum Number of Methods on MTS 2.0 Components Is 1024

MTS 1.0 had a limit of 100 methods per component. In MTS 2.0 this limit is now 1024 methods.

Components Using RDO 2.0 on Multiprocessor Computers May Experience Access Violations

Components that use RDO 2.0 and are accessed concurrently by multiple clients may experience access violations. This has been observed on servers that have multiple processors. This problem has not been observed for components that use ADO.

Location of Visual Basic Script Samples

The Visual Basic Scripting (VBScript) samples for automating MTS administration are located in \Program Files\Mts\Samples, not \Program Files\Mtx\Samples\WSH as stated in the documentation.

Java Sample Bank Does Not Compile on Windows 98

To compile the Java Sample Bank components on Windows 98, run midl.exe on the Account.idl file, then run SetJavaDev.bat.

Using the Microsoft Transaction Server API to Develop Applications Developing Components with Microsoft Visual C++ MFC Extension DLLs

MTS components should not be built as MFC Extension DLLs because such DLLs can be loaded only by MFC applications. A COM component, and therefore an MTS component, should be built so that it can be loaded into any process, regardless of the type of application that started the process.

For more information on MFC Extension DLLs, see the Microsoft Visual C++ Programmer’s Guide.

Developing Components with Microsoft Visual Basic ObjectControl

• The ObjectControl interface is the Automation counterpart of the C++ IObjectControl interface. The ObjectControl interface is not supported unless you have installed Microsoft Windows NT 4.0 Service Pack version 2 or later.
• The current Microsoft Transaction Server run-time implementation will call the CanBePooled method of a Transaction Server object, as specified in the Transaction Server online documentation. However, the return value is currently ignored. Returning TRUE does not stop Transaction Server from releasing your object.

Known Problem with Mtx.exe Shutdown When Using Visual Basic 4.0 Components

When an Mtx.exe process running Visual Basic 4.0 components is “Shutdown because idle for x minutes”, there is a known problem that results in a Read Access Violation. Currently there is no known solution to this problem. It is thought that if more than two Visual Basic 4.0 components are used in a process it is more likely to happen. One workaround is to set your package to “Leave running when idle”. This is only a problem when using components built with Visual Basic 4.0 — no such problem exists with Visual Basic 5.0.

Avoiding Visual Basic 4.0/RDO Deadlocks

If your server component uses RDO, never let an rdoConnection with an active rdoResultset fall out of scope or a deadlock may result. You must manually close the rdoResultset or rdoConnection to avoid the deadlock. The following sequence produces a deadlock:

1. Create an instance of the server component. Call a method which creates rdoConnection and then rdoResultset. You may fetch from, but do not exhaust or close the rdoResultset.
2. Release this instance. (As this connection and resultset go out of scope, the ODBC calls required are not immediately made. Instead, a message is posted to a hidden window to do the SQLFreeStmt+SQLDisconnect+SQLFreeConnect).
3. Create a second instance of the server component. Create an rdoConnection and attempt to update a row which was included in the resultset from Step 1 above. This is now a deadlock because the locks held for the resultset created in Step 1 have not been released. And the message pump which will process the message posted in Step 2 above will now never have a chance to run.

The deadlock is avoided by manually closing the resultset (or connection) at the end of Step 1, which immediately makes the ODBC calls to close the statement (and connection). The root of the problem is the delay introduced by the message posted to the hidden window to do the ODBC closes.

Maintaining the MTS Catalog when Developing Components with Visual Basic

Whenever you recompile an OLE DLL project in Visual Basic 4.0, Visual Basic rewrites all of the registry entries for all of the components (Visual Basic classes) that live in that DLL. Additionally, Visual Basic may generate new GUIDs (depending on your project configuration) to identify the components in that DLL. This means that your MTS components are no longer properly registered in the MTS catalog.

There are two solutions to this problem. First, there is a Refresh button in the Transaction Server Explorer, as well as the Refresh All Components command on the Tools menu. If you use this command Microsoft Transaction Server will repair all inconsistencies in registry entries of components currently in the right pane of the Explorer.

If you install the development version of Microsoft Transaction Server, check the VB Addin option to enable a feature that will automatically refresh your components after recompiling them. The next time you run Visual Basic 4.0, the add-in will be automatically installed in your Visual Basic IDE. You can also turn the feature on and off on a per-project basis by selecting or deselecting the MTxServer RegRefresh | AutoRefresh after compile command on the Visual Basic Add-Ins menu. If you decide you want to refresh all of your Microsoft Transaction Server components at any given time, you can use the MTxServer RegRefresh | Refresh all components now command on the Add-Ins menu.

Important The Visual Basic Add-in has been updated to work with both Visual Basic versions 4.0 and 5.0. Once installed, it will automatically refresh the Transaction Server catalog with the changes made during each compile. The add-in menu option to enable and disable the automatic refresh is no longer supported.

Using the add-in will properly refresh the MTS catalog, even after Visual Basic compilations that generate new component GUIDs. Note also that the Compatible OLE Server setting in the Visual Basic Project Options dialog box can be used to stop Visual Basic from generating new component GUIDs.

Refreshing the MTS catalog depends on you not changing the ProgIDs of your components. In Visual Basic 4.0, a component’s ProgID is formed by the following concatenation: project name.class name. If you change either of these items, you will have to reinstall your component(s) in the MTS Explorer.

Building your component in Visual Basic 4.0 without selecting the Compatible OLE Server option replaces your old CLSID and IID on each compile. This has disadvantages when developing an MTS component, even with the Visual Basic add-in enabled.

• Roles you assigned to the interface using the MTS Explorer are lost, since the interface IID is obsolete.
• Proxies and registry configurations you distributed to remote machines no longer refer to your component and must all be updated.
• Packages you exported which contain your component require re-exporting since the package definition file GUIDs are now out of sync.

Copyright Information

© 1997 Microsoft Corporation

These materials are provided “as-is,” for informational purposes only.

Neither Microsoft nor its suppliers makes any warranty, express or implied with respect to the content of these materials or the accuracy of any information contained herein, including, without limitation, the implied warranties of merchantability or fitness for a particular purpose. Because some states/jurisdictions do not allow exclusions of implied warranties, the above limitation may not apply to you.

Neither Microsoft nor its suppliers shall have any liability for any damages whatsoever including consequential, incidental, direct, indirect, special, and lost profits. Because some states/jurisdictions do not allow exclusions of implied warranties, the above limitation may not apply to you. In any event, Microsoft’s and its suppliers’ entire liability in any manner arising out of these materials, whether by tort, contract, or otherwise shall not exceed the suggested retail price of these materials.

© 1998 by Microsoft Corporation. All rights reserved.