ファースト ステップ ガイド

Microsoftｮ Transaction Server (MTS) は、コンポーネントベースのトランザクション処理システムとして、高性能でスケーラブル、かつ堅牢な企業向けインターネット、およびイントラネット サーバー アプリケーションの開発、配置、および管理機能を提供します。MTS では、コンポーネントベースの分散アプリケーションを開発するためのプログラミング モデルが定義されています。また、これらのアプリケーションの配置と管理のためのランタイム環境とグラフィカル ツールが用意されています。

ここでは、MTS の新しい機能とドキュメントの概要を説明し、用語についても解説します。ここでは以下のトピックについて説明します。

•	新しい機能

•	ドキュメントの構成

•	用語集

•	ユーティリティ

•	よく寄せられる質問 (FAQ)


新しい機能

Microsoft Transaction Server (MTS) Version 2.0 には、堅牢でスケーラブルなインターネットおよびイントラネット アプリケーションの配置を容易にする多くの新しい機能が用意されています。ここでは MTS の新しい機能の概要を説明します。

Internet Information Server (IIS) Version 4.0 との完全な統合

MTS 2.0 は IIS 4.0 と完全に統合されており、Web 上のビジネス アプリケーションにとって最適なプラットフォームを提供します。MTS と IIS の統合により、次のような新しい機能が提供されます。

•	トランザクションで使用できる Active Server Pages

MTS が管理するトランザクション内で Active Server Pages のスクリプトを実行できます。このため、MTS トランザクションに対する保護が Web アプリケーション全体に適用されます。

•	IIS アプリケーションに対するクラッシュ保護

IIS Web アプリケーションを Web アプリケーション自身の MTS パッケージ内で実行できるので、Web アプリケーションのプロセスを分離し、クラッシュから保護することができます。

•	トランザクションに基づくイベント

開発者は Active Server Pages のスクリプトにコマンドを埋め込むことができるので、Web アプリケーションの応答をトランザクションの結果に基づいてカスタマイズできます。

•	IIS 組み込みオブジェクトのオブジェクト コンテキスト

MTS オブジェクト コンテキストによって、アプリケーション開発者がユーザーの状態情報を追跡するときの複雑さは軽減され、IIS 組み込みオブジェクトに管理された状態情報を追跡することができます。このため、Web 開発者は MTS プログラミング モデルの簡易性を活用できます。

•	共通のインストールと管理

MTS と IIS が共通のインストールと共通の管理コンソールを共有できるので、Web 上のビジネス アプリケーションの配置と管理の複雑さが軽減されます。

Oracle のネイティブ サポートを含む XA トランザクション プロトコルのサポート

•	MTS 2.0 は XA トランザクション プロトコルをサポートしています。このため、MTS アプリケーションは ODBC を介して Windows NT Server 上および (UNIX の各バージョンを含む) Microsoft 以外のオペレーティング システム上で動作する IBM DB2、Informix などの XA 準拠データベースと組み合わせて使用できます。

•	MTS 2.0 には、 Microsoft Oracle Driver for Oracle の改訂版が含まれているので、MTS アプリケーションは ODBC を介して Oracle Version 7.3 以降と連携し、トランザクションを直接管理することができます。

デスクトップ オペレーティング システムのサポート

MTS 2.0 は Windows NT Version 4.0 以降と Windows 95/98 の両方のオペレーティング システムで使用できます。MTS は、 Microsoft のデスクトップ オペレーティング システムに対応しているため、企業は独自の MTS アプリケーションのスタンドアロン バージョンを配置することができます。

•	Windows NT Server に MTS コンポーネントを配置する前に、MTS コンポーネントを開発するための開発プラットフォームとして Windows 95/98 を利用できます。また、Windows NT 上で実行している MTS サーバー アプリケーションの管理クライアントとして Windows 95/98 コンピュータを使うこともできます。さらに、MTS は Windows 95/98 上で実行する Personal Web Server (PWS) のランタイム環境も提供します。

•	Windows NT と Windows 95/98 との違いにより、Windows 95/98 上の MTS は Microsoft Cluster Server や MTS のロールに基づくセキュリティをサポートしていません。Windows NT または Windows 95/98 を実行しているコンピュータから MTS を実行している Windows 95/98 コンピュータをリモートで管理することはできません。また、MTS 管理の自動化を示す Microsoft Visual Basicｮ Scripting Edition (VBScript) のサンプルは、Windows 95/98 コンピュータにはインストールされません。

Microsoft Cluster Server のサポート

MTS 2.0 は Microsoft Cluster Server (MSCS) をサポートしています。このため、クラスタ内の MTS パッケージの自動フェールオーバーが可能です。自動フェールオーバーにより MTS アプリケーションの高可用性が実現されます。

LU 6.2 Sync Level 2 を介した CICS および IMS トランザクションのサポート

MTS 2.0 を使うと、企業は MVS 上の CICS および IMS トランザクションをサポートする MTS アプリケーションを配置することができます。MTS は、MTS と CICS/MVS および IMS/MVS との間の相互運用性を提供する SNA サーバー コンポーネントである COM トランザクション インテグレータ (COMTI) を完全にサポートします。

管理機能の拡張

MTS 2.0 では次のような管理機能の拡張により、MTS パッケージの配置と管理がさらに容易になっています。

•	MTS エクスプローラのスナップイン

MTS エクスプローラは、Microsoft Management Console (MMC) のスナップインになっています。このため、IIS などのほかの製品と同じ管理コンソールを使って MTS パッケージを管理できます。MMC およびスナップインの使い方の詳細については、MMC のドキュメントを参照してください。

•	個々のサーバー プロセスのシャットダウン

MTS 2.0 では、MTS サーバー プロセスをシャットダウンせずに、MTS エクスプローラで個々のパッケージをシャットダウンできます。パッケージをシャットダウンすると、そのアプリケーションのサーバー プロセスは終了します。MTS 1.x コンピュータ上のリモートで管理されているパッケージは、個別にシャットダウンすることはできません。

•	改良されたパッケージのアクティブ化の設定

MTS 2.0 では、アクティブ化はパッケージ レベルだけに設定されます。同じパッケージ内の複数のコンポーネントに異なるアクティブ化を設定することはできません。また、リモートでのアクティブ化を設定してパッケージを実行することもできません。パッケージは、サーバー (ローカルでのコンポーネントのアクティブ化) またはライブラリ (コンポーネントを呼び出したクライアントと同じプロセスでのアクティブ化) のいずれかに設定されます。

含まれているすべてのコンポーネントがインプロセスに指定されている MTS 1.0 のパッケージは、MTS 2.0 をインストールすると、自動的にライブラリ パッケージにアップグレードされます。含まれているすべてのコンポーネントがローカルでのアクティブ化に指定されている MTS 1.0 のパッケージは、自動的にサーバー パッケージにアップグレードされます。異なる方式のコンポーネントのアクティブ化が混在している MTS 1.0 のパッケージは、手動でライブラリ パッケージまたはサーバー パッケージとして構成する必要があります。

•	プロパティの更新時に複数アイテムの選択が可能

MTS エクスプローラで複数のアイテムのプロパティを同時に選択し、変更することができます。

プログラミング機能の拡張

MTS 2.0 では次のようなプログラミング機能の拡張により、MTS アプリケーションの作成がさらに容易になっています。

•	MTS サンプル アプリケーションの追加と更新

Sample Bank アプリケーションが更新され、新たに 2 つのサンプル アプリケーションが提供されます。Tic-Tac-Toe サンプル アプリケーションは、共有状態を管理する非トランザクション コンポーネントの機能を示す簡単なマルチユーザー ゲームです。Administrative Sample Scripts は、管理スクリプト オブジェクトを使用し、Windowsｮ Scripting Host スクリプトによってエクスプローラの処理を自動化する方法を示します。

•	管理スクリプト オブジェクト

管理スクリプト オブジェクトを使って、MTS エクスプローラによるパッケージの配置と保守を自動化することができます。オートメーション互換の任意の言語を使うことにより、パッケージのインストールなどの管理手順を簡単なスクリプトを使って自動化することができます。

•	MTS アプリケーションの設計と実装に関するドキュメント

『Programmer's Guide』は、MTS アプリケーションを作成するときの設計および実装に関する手引き書です。コンポーネントへのビジネス ロジックの組み込みから問題の診断とデバッグまでのトピックについて説明します。

関連項目

『管理者ガイド』、MTS Overview and Concepts (概要とプログラミングの概念)


ドキュメントの構成

Microsoft Transaction Server (MTS) には、MTS アプリケーションの設計、構築、配置、および管理の学習に役立つ次のドキュメントが用意されています。

ドキュメント	内容
『セットアップ』	MTS と MTS コンポーネントのセットアップ方法を説明します。MTS アプリケーションから Oracle データベースにアクセスする手順と、MTS サンプル アプリケーションをインストールする手順についても説明します。
『ファースト ステップ ガイド』	MTS の新しい機能とドキュメントの概要を説明し、用語についても解説します。
『クイック ツアー』	MTS の概要を説明します。
『管理者ガイド』
管理者ガイド	MTS エクスプローラを使ってアプリケーションの配置と管理を行うさまざまな方法と、MTS エクスプローラのグラフィカル インターフェイスの概要を説明します。
パッケージの作成	MTS パッケージの作成と組み込みについて、作業と手順に沿って説明します。
パッケージの配布	MTS パッケージの配布について、作業と手順に沿って説明します。
パッケージのインストール	MTS パッケージのインストールと構成について、作業と手順に沿って説明します。
パッケージの保守	MTS パッケージの保守と監視について、作業と手順に沿って説明します。
トランザクションの管理	分散トランザクションと、MTS エクスプローラを使ったトランザクションの管理について説明します。
管理の自動化	概念的な概要、操作手順、サンプル コードを示し、MTS スクリプト オブジェクトのスクリプトを使って MTS エクスプローラの処理を自動化する方法について説明します。
『Programmer's Guide』
MTS Overview and Concepts (概要とプログラミングの概念)	MTS の概要および MTS のコンポーネントどうしが協調して動作するしくみを説明します。また、クライアント/サーバー開発者とシステム管理者のニーズに MTS がどのように応えるかを説明し、MTS コンポーネントのプログラミングの概念について詳しく解説します。
Building MTS Applications (アプリケーションの作成)	MTS 用の ActiveXｮ コンポーネントの開発について、作業と手順に沿って説明します。
MTS Administrative Reference (管理リファレンス)	MTS スクリプト オブジェクトを使って MTS エクスプローラの処理を自動化するための参照情報が記載されています。
MTS Reference (リファレンス)	MTS アプリケーション プログラミング インターフェイス (API) に関する参照情報が記載されています。


ユーティリティ

MTS には、バッチ ファイルで特定の作業を自動化するためのコマンドライン ユーティリティが用意されています (これらのユーティリティはコマンド プロンプトから直接使用できます)。

コマンドライン ユーティリティ

次の表は、MTS と一緒にインストールされるコマンドライン ユーティリティのクイック リファレンスです。

ユーティリティ	機能
MTXSTOP.exe	MTS のすべてのプロセスをシャットダウンします。[マイ コンピュータ] をマウスの右ボタンでクリックすると表示されるメニューの [サーバー プロセスのシャットダウン] コマンドに対応するコマンドライン ユーティリティです。
MTXREREG.exe	ローカル コンピュータに登録されているすべてのコンポーネントを更新します。選択したコンピュータをマウスの右ボタンでクリックすると表示されるメニューの [すべてのコンポーネントの更新] コマンドに対応するコマンドライン ユーティリティです。
MTXREPL.exe	MTS サーバーをレプリケートします。レプリケート元コンピュータとレプリケート先コンピュータの両方を実行している必要があります。
TestOracleXAConfig.exe	MTS コンポーネントを含む分散トランザクションを確認するために Oracle の構成をテストします。 このユーティリティが失敗した場合、Oracle データベースを使用する分散トランザクションは動作しません。
Windows NT の管理ツール

Windows NT にも MTS アプリケーションの管理に使用できるツールがいくつか用意されています。これらのツールを使うには、[スタート] ボタンをクリックし、[プログラム] をポイントします。次に、[管理ツール (共通)] をポイントします。

ツール		機能
	イベント ビューア	Windows NT で、イベントとは、システムまたはプログラムで発生し、ユーザーに通知する必要のある重要なできごとのことです。イベント ビューアは、イベントをユーザーに通知したり、ログに記録したりします。MTS アプリケーションで発生した問題を診断するときは、まずイベント ビューアを参照してください。
	パフォーマンス モニタ	パフォーマンス モニタは、自分のコンピュータ、またはネットワーク上のほかのコンピュータのパフォーマンスを監視するためのツールです。
	サーバー マネージャ	サーバー マネージャは、同じドメインのワークステーションとサーバーの一覧を表示します。
	ドメイン ユーザー マネージャ	ドメイン ユーザー マネージャを使うと、ドメインのユーザー アカウントを作成または削除したり、無効にしたりすることができます。また、セキュリティの原則を設定し、ユーザー アカウントをグループに追加することもできます。
	Windows NT 診断プログラム	Windows NT 診断プログラムは、コンピュータのリソースに関する情報を表示します。
注意   これらの Windows NT の管理ツールを使うには、管理者権限を持つアカウントでコンピュータにログオンする必要があります。

関連情報

『管理者ガイド』


よく寄せられる質問 (FAQ)

Microsoft Transaction Server についてよく寄せられる質問は、http://www.microsoft.com/japan/support/ に記載されています。


Microsoft Transaction Server のクイック ツアー

Microsoftｮ Transaction Server (MTS) は、コンポーネントベースのトランザクション処理システムとして、高性能でスケーラブル、かつ堅牢な企業向けインターネット、およびイントラネット サーバー アプリケーションの開発、配置、および管理機能を提供します。

以下のトピックでは、Microsoft Transaction Server の各機能について説明します。

•	Microsoft Transaction Server とは

•	Microsoft Transaction Server ランタイム環境

•	Microsoft Transaction Server エクスプローラ

•	Microsoft Transaction Server API

•	Microsoft Transaction Server サンプル アプリケーション


Microsoft Transaction Server とは

MTS は、コンポーネントベースのトランザクション処理システムとして、堅牢なインターネットおよびイントラネット サーバー アプリケーションの構築、配置、および管理機能を提供します。また、MTS では、豊富な機能を備えたグラフィカル ツール (MTS エクスプローラ) を使って MTS サーバー アプリケーションを配置し、管理することができます。

MTS は次のような機能を提供します。

	MTS ランタイム環境。
	アプリケーション コンポーネントの配置と管理のためのグラフィカル ユーザー インターフェイスである MTS エクスプローラ。
	スケーラブルで堅牢なアプリケーションの構築のためのアプリケーション プログラミング インターフェイスと "リソース ディスペンサ"。リソース ディスペンサは、プロセス内部のアプリケーション コンポーネントに代わって、持続しない共有状態を管理するサービスです。
	アプリケーション プログラミング インターフェイス (API) を使って MTS コンポーネントを作成する方法と、管理スクリプト オブジェクトを使って MTS エクスプローラでの配置処理を自動化する方法を示す 3 つのサンプル アプリケーション。
MTS プログラミング モデルは、ビジネス ロジックをカプセル化するコンポーネントを開発するためのフレームワークを提供します。MTS ランタイム環境は、これらのコンポーネントを実行するための中間層のプラットフォームです。MTS エクスプローラを使って、MTS ランタイム環境で実行されるコンポーネントを登録し、管理することができます。

このような 3 階層のプログラミング モデルによって、開発者と管理者は 2 階層のクライアント/サーバー アプリケーションの制約を乗り越える可能性を得ます。3 階層のアプリケーションでは、次に示す理由から、配置と管理の柔軟性が向上します。

•	3 階層のモデルでは、アプリケーションの物理アーキテクチャより論理アーキテクチャのほうが重視されます。どのサービスからでもほかのサービスを呼び出すことができます。また、サービスがどこに存在していてもかまいません。

•	これらのアプリケーションは配布されます。これは、適切なコンポーネントを適切な場所で実行できることを意味しています。その結果、ユーザーに利点があると同時に、ネットワーク リソースとコンピュータ リソースの使用効率が最適化されます。

関連項目

ドキュメントの構成


Microsoft Transaction Server ランタイム環境

MTS ランタイム環境によって、アプリケーション開発者やシステム管理者は、包括的で使いやすい一連のシステム サービスを利用し、アプリケーションを容易に開発、配置、および管理できるようになります。これらのサービスには、次のようなものがあります。

•	分散トランザクション。"トランザクション" とは、アトミックな処理として実行される動作の単位のことです。つまり、処理は全体として成功するか、失敗するかのいずれかの結果になります。

•	プロセスとスレッドの自動管理。

•	オブジェクト インスタンス管理。

•	オブジェクトの作成と使用を制御する分散セキュリティ サービス。

•	システム管理とコンポーネント管理のためのグラフィカル インターフェイス。

アプリケーション開発者は、これらのシステム サービスを利用することによって、アプリケーションにスケーラビリティと堅牢性をもたらすことができます。このため、システム環境の開発から解放され、業務上の問題解決に集中できるようになります。

MTS は、ActiveX� ダイナミック リンク ライブラリ (DLL) を生成できるアプリケーション開発ツールであれば、どのようなツールとでも組み合わせて使用できます。たとえば、Microsoft Visual Basicｮ、Microsoft Visual C++ｮ、Microsoft Visual J++ｮ、またはそのほかの ActiveX ツールを使って、MTS アプリケーションを開発できます。

MTS は、リレーショナル データベース システム、ファイル システム、ドキュメント格納システムなど、さまざまなリソース マネージャと組み合わせて利用できるように設計されています。このため、開発者やソフトウェア メーカーは、さまざまなリソース マネージャの中から必要なものを選択し、ローカル トランザクションまたは分散トランザクションの利点を活用しながら、単一のアプリケーションで複数のリソース マネージャを簡単に利用することができます。

関連項目

MTS Overview and Concepts (概要とプログラミングの概念)


Microsoft Transaction Server エクスプローラ

MTS エクスプローラは、MTS コンポーネントを管理し、配置するためのグラフィカル ユーザー インターフェイスです。開発者と同様にシステム管理者や Web 管理者は、MTS エクスプローラを使ってパッケージの管理、配布、インストール、配置、およびテストを行うことができます。開発者は、MTS エクスプローラを使って、コンポーネントを組み合わせて既成のパッケージを作成したり、MTS 環境でコンポーネントを配布したり、テストしたりすることができます。また、管理者や開発者は、MTS エクスプローラを使ってコンポーネントとパッケージのインストール、配置、および保守を行うこともできます。さらに、MTS エクスプローラを使うと、トランザクション コンポーネントのトランザクションを監視し、管理することができます。

MTS エクスプローラの階層は、次のようなランタイム環境のアイテムがどのように構成されているかを表します。

•	コンピュータ

•	パッケージ

•	コンポーネント

•	ロール

•	インターフェイス

•	メソッド

MTS パッケージはコンピュータにインストールされ、コンポーネントを含み、ロールを定義します。パッケージ内のコンポーネントはインターフェイスとメソッドを定義します。専用のウィンドウを使ってトランザクションとトレース メッセージに関する情報を表示することができます。

次の図は、MTS エクスプローラのウィンドウの左側に階層がどのように表示されるかを示しています。

プロパティ表示のウィンドウを使って、パッケージ内のコンポーネントのプロパティやコンピュータにインストールされているパッケージを表示することができます。

[トランザクションの統計] ウィンドウを使って、最近のトランザクションの状態を概略として表す統計情報を表示することもできます。

MTS エクスプローラの操作

MTS エクスプローラのウィンドウの左側には階層が表示され、右側には左側でクリックしたアイテムの内容が表示されます。階層は、フォルダと、MTS エクスプローラを使って構成できるすべてのアイテムを含んだツリー構造になっています。

アイテムの内容を表示するには、ウィンドウの右側でフォルダやアイテムをダブルクリックして MTS エクスプローラの階層を移動します。ウィンドウの左側でフォルダやアイテムをクリックして、右側にその内容を表示することもできます。階層の中の任意のアイテムを展開するには、アイテムの横のプラス記号 (+) をクリックします。そのアイテムの階層がウィンドウの左側に表示されます。ウィンドウの左側でフォルダやアイテムをダブルクリックすると、その内容が右側に表示され、階層の表示を展開したり、折りたたんだりできます。

ウィンドウの左側、右側のどちらでも、方向キーを使ってアイテムを選択することができます。ウィンドウの右側で Enter キーを押すと、そのアイテムの内容が表示されます。Tab キーを押すと、MTS エクスプローラのウィンドウの左右を交互に移動できます。

Windowsｮ 95/98 では、MTS エクスプローラのウィンドウの左側にツリー構造が表示されないことに注意してください。階層を下に移動するにはアイコンをダブルクリックし、階層を上に移動するにはツール バーの [1 つ上のレベル] ボタンをクリックします。Windows 95/98 での MTS エクスプローラの使い方の詳細については、『管理者ガイド』を参照してください。

アイテムのプロパティの設定と表示

MTS エクスプローラの階層に追加されたアイテムに関する基本的な情報は、そのアイテムの [プロパティ] ダイアログ ボックスに表示されます。表示される情報は、アイテムの種類によって異なります。たとえば、コンピュータの [プロパティ] ダイアログ ボックスには、コンピュータ名、ログ ファイルの場所、更新の設定などが表示されます。パッケージの [プロパティ] ダイアログ ボックスには、セキュリティやそのほかのプロセス固有の設定に関する情報が表示されます。

[プロパティ] ダイアログ ボックスを表示するには、アイテムを選択し、[動作] メニューの [プロパティ] をクリックするか、またはアイテムをマウスの右ボタンでクリックし、[プロパティ] をクリックします。[プロパティ] ダイアログ ボックスには複数のタブがあり、それぞれのタブをクリックしてタブを切り替えます。

トランザクションの監視と解決

MTS ランタイム環境には、トランザクション処理を広範囲にサポートする機能が用意されています。Microsoft 分散トランザクション コーディネータ (MS DTC) は、MTS でのトランザクション処理をサポートします。MS DTC は Windows NTｮ のサービスです。MTS は MS DTC を使って、トランザクションの完了前にトランザクションのすべての関連部分が同意状態にあることを確認します。

トランザクションのサポートは、MTS エクスプローラの階層の中で、次の 3 つのウィンドウを通じて提供されます。

	[トランザクションの一覧] ウィンドウは、アクティブ トランザクションの状態を監視するときに使います。
	[トランザクションの統計] ウィンドウは、最近のトランザクションの統計情報を表示するときに使います。
	[トレース メッセージ] ウィンドウは、トランザクション処理に関連するトレース メッセージを表示するときに使います。
関連項目

『管理者ガイド』


Microsoft Transaction Server API

MTS アプリケーション プログラミング インターフェイス (API) を使用して MTS ランタイム環境の機能を活用するスケーラブルで堅牢なアプリケーションを開発したり、パッケージとコンポーネントの管理を自動化したりできます。

クライアント アプリケーションの開発

MTS ランタイム環境の外部で実行されるクライアント アプリケーションは、標準の COM ライブラリ関数 (C++ では CoCreateInstance、Visual Basic では CreateObject メソッド) を使って MTS オブジェクトのインスタンスを生成します。

コンポーネントの開発

MTS コンポーネント (MTS ランタイム環境に登録されるサーバー コンポーネント) を開発する場合は、MTS の IObjectContext、ISharedPropertyGroupManager、ISharedPropertyGroup、および ISharedProperty の各インターフェイスを使用して次の作業を行うことができます。

•	オブジェクトの動作の完了を宣言する。

•	トランザクションがコミットされないようにする。

•	ほかの MTS オブジェクトを作成する。

•	ほかのオブジェクトの動作をカレント オブジェクトのトランザクションのスコープに含める。

•	呼び出し元が特定のロールを持っているかどうかを判断する。

•	セキュリティが有効になっているかどうかを判断する。

MTS 管理の自動化

MTS 管理オブジェクトを使って、パッケージとコンポーネントの管理を自動化できます。Visual Basic、Visual Basic Scripting Edition (VBScript)、またはそのほかの任意のオートメーション互換言語を使って、既成のパッケージのインストールから関連コレクションの列挙までの MTS エクスプローラの処理を自動化できます。

関連項目

『管理者ガイド』、MTS Overview and Concepts (概要とプログラミングの概念)、MTS Reference (リファレンス)、MTS Administrative Reference (管理リファレンス)


Microsoft Transaction Server サンプル アプリケーション

MTS には、ドキュメントのほかに、学習ツールとして役立つサンプル アプリケーションが用意されています。これらのアプリケーションの一部を自分のアプリケーションにコピーし、必要に応じて修正して使うこともできます。

『Programmer's Guide』の全体を通じて、MTS のプログラミング技法を示すサンプル コードやアプリケーションが記述されています。これらのアプリケーションのファイルの多くは、セットアップ時にインストールされます。アプリケーションのソース ファイルは、MTS がインストールされているディレクトリの \Samples フォルダにあります。

MTS には、次のサンプル アプリケーションが用意されています。

サンプル	説明
Sample Bank	MTS アプリケーション プログラミング インターフェイス の使い方を示す簡単なトランザクション データベース アプリケーションです。
Tic-Tac-Toe	共有状態を管理する非トランザクション コンポーネントの機能を示す簡単なマルチユーザー ゲームです。
Administrative Sample Scripts	VBScript を使って MTS エクスプローラの処理を自動化する方法を示す管理オブジェクト スクリプトです。
関連項目

開発者用サンプルとドキュメントのインストール、Sample Bank アプリケーションのセットアップ、Tic-Tac-Toe サンプル アプリケーションのセットアップ、管理オブジェクト サンプル スクリプトのセットアップ、MTS Overview and Concepts (概要とプログラミングの概念)、MTS 管理自動化 Visual Basic Script サンプル


セットアップ

Microsoftｮ Transaction Server (MTS) へようこそ。MTS は、高性能でスケーラブル、かつ堅牢な企業向けインターネット、およびイントラネット アプリケーションの開発と配置を容易にする強力な環境を提供します。MTS では、コンポーネントベースの分散アプリケーションを開発するためのプログラミング モデルが定義されています。また、これらのアプリケーションの配置と管理のためのランタイム環境も提供します。

MTS のインストールとセットアップの方法については、次のトピックを参照してください。

•	システムの必要条件

•	開発者用サンプルとドキュメントのインストール

•	MTS サーバーの構成

•	MTS を Microsoft Cluster Server と組み合わせて使うように構成する

•	MTS を Oracle にアクセスできるように設定する

•	Sample Bank アプリケーションのセットアップ

•	Tic-Tac-Toe サンプル アプリケーションのセットアップ

•	管理オブジェクト サンプル スクリプトのセットアップ

•	MTS に関する情報の入手


システムの必要条件

ここでは、MTS のインストールに必要なハードウェアとソフトウェアの条件、セットアップに関する注意事項、および Alpha プラットフォームに対する MTS のサポートについて説明します。

MTS は次のいずれかの方法でコンピュータにインストールできます。

•	Windows NTｮ Version 4.0 Option Pack を使って、Internet Information Server (IIS) などの Option Pack コンポーネントと一緒に MTS をインストールする方法。

•	Windows NT Version 4.0 Option Pack を使って、ほかの Option Pack コンポーネントとは別に MTS だけをインストールする方法。

MTS は、Windows NT、Windowsｮ 98、および DCOM がインストールされている Windowsｮ 95 上で動作します。

重要:  IIS 2.0 または IIS 3.0 を既に使用している場合は、Windows NT Option Pack の IIS 4.0 と共に MTS をインストールしてください。

ほかの Option Pack コンポーネントとは別に MTS だけをインストールするには、次の操作を行います。

1	Option Pack セットアップ プログラムを実行し、[カスタム] をクリックします。

2	すべての Option Pack コンポーネントのチェック ボックスをオフにします。

3	チェック ボックスはオンにせずに [Transaction Server] を選択します。

4	[サブコンポーネントの表示] をクリックします。

5	[Microsoft Transaction Server コア コンポーネント] チェック ボックスをオンにします。[Microsoft Management Console] チェック ボックスもオンになります。

[Transaction Server Development] オプションを選択すると、データ アクセス コンポーネントもインストールされることに注意してください。

6	[OK] をクリックし、セットアップ プログラムを継続します。

ハードウェアの必要条件

Microsoft Transaction Server をインストールする前に、コンピュータが次の必要条件を満たしていることを確認してください。

•	Windows NT、Windows 98、または DCOM がインストールされている Windows 95 を実行している i386 互換コンピュータまたは Alpha AXP� コンピュータ。ハードウェアの必要条件の最新情報については、MTS Readme を参照してください。

•	すべてのコンポーネントをインストールする場合は、30 MB 以上の空き容量があるハード ディスク。

•	CD-ROM ドライブ。

•	Windows NT Version 4.0 以降または Windows 95/98 対応のディスプレイ。

•	32MB 以上のメモリ。

•	マウスまたはそのほかのポインティング デバイス。

Windows NT Version 4.0 Option Pack セットアップ プログラムを使って、MTS のセットアップを無人モードで実行できます。無人セットアップを実行する前に、セットアップ ファイルをセットアップの選択項目に応じて変更してください。無人セットアップの詳細については、Windows NT 4.0 Option Pack オンライン ドキュメントの『ファースト ステップ ガイド』の「Windows NT 4.0 Option Pack のセットアップ」の「Option Pack のインストール」の「Option Pack の無人インストール」を参照してください。

無人セットアップを実行するには、[スタート] ボタンをクリックし、[ファイル名を指定して実行] をクリックします。次に、次のように入力します。

setup /u:unattend.txt

ソフトウェアの必要条件

ソフトウェアの必要条件は次のとおりです。

•	MTS をインストールする前に、Windows NT Version 4.0 以降、Windows 98、または Windows 95 と DCOM for Windows 95 をコンピュータにインストールしなければなりません。MTS をセットアップする前に DCOM for Windows 95 をインストールしないと、次のエラー メッセージが表示されます。

"セットアップ ライブラリ mtssetup.dll を読み込めなかったか、関数 MTSSetupProc が見つかりませんでした。"

DCOM for Windows 95 は、http://www.microsoft.com/japan/win95/ からインストールできます。DCOM for Windows 95 は Internet Explorer 4.0 が自動的にインストールすることに注意してください。Windows 98 をインストールすると、DCOM もインストールされます。

Windows 95 コンピュータから MTS を削除する場合は、DCOM for Windows 95 を削除しないでください。DCOM for Windows 95 が必要な Microsoft 分散トランザクション コーディネータ (MS DTC) は、MTS セットアップ プログラムによってインストールされますが、削除されません。

•	Windows 95/98 コンピュータから Windows NT コンピュータをリモートで管理する場合は、リモート レジストリ サービスをインストールしなければなりません。リモート レジストリ サービスを使うと、(適切なアクセス権があれば) リモートの Windows NT コンピュータのレジストリ エントリを変更することができます。リモート レジストリ サービスは、Windows 95/98 の CD-ROM の \Admin\Nettols\RemotReg ディレクトリにあります。リモート レジストリ サービスをインストールする方法については、Regserv.txt ファイルを参照してください。

•	Microsoft Windows 95 クライアントを MTS と共に使用する場合は、DCOM for Windows 95 をインストールします。DCOM for Windows 95 の最新情報については、http://www.microsoft.com/japan/win95/を参照してください。Windows 98 をインストールすると、DCOM もインストールされます。

•	Windows NT Server Version 4.0を使用している場合は、Windows NT 4.0 Service Pack 3 をインストールしなければなりません。Windows NT 4.0 Service Pack 3 は、http://www.microsoft.com/products/ntupdate/nt4sp3/ からダウンロードできます。

•	コンポーネントを使ってデータベースにアクセスする場合は、Microsoft SQL Server Version 6.5 以降、またはそのほかの Microsoft Transaction Server 互換のデータベースを使用してください。SQL Server を使用するには Windows NT オペレーティング システムが必要です。

•	MTS ソフトウェアを実行するコンピュータには SQL Server 6.5 Service Pack 4 をインストールすることを強くお勧めします。既知の障害のいくつかは、この Service Pack によって解決できます。SQL Server 6.5 Service Pack 4 は、http://www.microsoft.com/japan/bkoffice/ntsql/ からインストールできます。

•	Microsoft Visual Basicｮ を使ってコンポーネントを作成する場合は、Microsoft Visual Basic Version 4.0 以降の Enterprise Edition を使用してください。MTS コンポーネントの作成には、Visual Basic Version 5.0 以降を使用することを強くお勧めします。

Visual Basic を使って DLL を作成する場合は、MTS のインストールで [カスタム] オプションを選択して VB アドインをインストールします。アドインを使用すると、Visual Basic がコンパイル中に新しいコンポーネント GUID を生成した後でも MTS カタログを正しく更新することができます。詳細については、「MTS Component Requirements」 を参照してください。

•	Microsoft Visual C++ｮ を使ってコンポーネントを作成する場合は、Visual C++ Verison 4.1 以降を Active Template Libraries (ATL) Version 1.1 以降と組み合わせて使用してください。Visual C++ Version 4.1 を使用する場合は、Win32ｮ SDK が必要です。

•	Java コンポーネントを作成し、MTS と共に実行する場合は、Internet Explorer Version 4.0 以降と一緒にインストールされる Microsoft Virtual Machine for Java を使用してください。Internet Explorer は、http://www.microsoft.com/japan/ie/ からダウンロードできます。

•	インターネット アプリケーションを作成する場合は、Microsoft Internet Information Server Version 4.0 以降、および Microsoft Internet Explorer Version 4.0 以降を使用しなければなりません。

•	Oracle データベースを MTS と組み合わせて使用することができます。Oracle を MＴＳ と組み合わせて使用する場合は、「MTS を Oracle にアクセスできるように設定する」を参照してください。

MTS 1.x コンピュータから MTS 2.0 コンピュータをリモートで管理できない

以前のバージョンの MTS を実行中のコンピュータから、インストールされた MTS 2.0 をリモートで管理することはできません。これを試みた場合、エラー コードが返されるか、MTS エクスプローラが予期せず終了します。

MTS 2.0 インストール後の Visual Basic 5.0 のシャットダウン

MTS 2.0 のインストール後に Microsoft Visual Basic 5.0 をシャットダウンすると、アクセス違反が発生する場合があります。これは Visual Basic 5.0 の既知の問題で、Visual Studio Service Pack 2 以降を http://www.microsoft.com/japan/developer/vstudio からインストールすると解決できます。この問題の詳細については、Knowledge Base の J041291 を参照してください。

名前付きパイプを使用したときの Windows 95/98 のデッドロック

Windows 95/98 クライアントから MS SQL Server へ約 40 以上の名前付きパイプ接続を使用すると、デッドロックを起こす可能性があります。この問題を解決するには、ODBC ドライバと SQL Server 間のプロトコルを TCP/IP に変更します。

INSTCAT.SQL スクリプトの実行

MTS は INSTCAT.SQL スクリプトを提供します。このスクリプトは、SQL Server ODBC Driver に対するカタログ ストアド プロシージャを更新します。このスクリプトを実行していない場合は、SQL Server の ISQL ユーティリティを使ってスクリプトを実行してください。このスクリプトは、SQL Server カタログで起こりうる、バージョン番号の潜在的な不一致を解決します。

MTS と共に SQL Server をインストールする

SQL Server 6.5 を MTS のインストール後にインストールすることができますが、SQL Server 6.5 は MTS をインストールする前にインストールすることをお勧めします。MTS のインストール後に SQL Server 6.5 をインストールすると、MTS セットアップは MS DTC が正しく動作するかどうかを確認しようとします。

MTS 2.0 に MTS 1.0 を上書きインストールする

MTS 2.0 がインストールされているコンピュータに MTS 1.0 をインストールするときは、MTS 1.0 のセットアップを実行する前に、system ディレクトリから次のファイルを削除しなければなりません。

%WINDIR%\system32\adme.dll

%WINDIR%\system32\dac.exe

%WINDIR%\system32\dacdll.dll

%WINDIR%\system32\dtccm.dll

%WINDIR%\system32\dtctrace.dll

%WINDIR%\system32\dtctrace.exe

%WINDIR%\system32\dtcuic.dll

%WINDIR%\system32\dtcuis.dll

%WINDIR%\system32\dtcutil.dll

%WINDIR%\system32\dtcxatm.dll

%WINDIR%\system32\enudtc.dll

%WINDIR%\system32\logmgr.dll

%WINDIR%\system32\msdtc.exe

%WINDIR%\system32\msdtc.dll

%WINDIR%\system32\msdtcprx.dll

%WINDIR%\system32\msdtctm.dll

%WINDIR%\system32\dtccfg.cpl

%WINDIR%\system32\svcsrvl.dll

%WINDIR%\system32\xolehlp.dll

%WINDIR%\system32\mmc.exe

%WINDIR%\system32\mmc.ini

%WINDIR%\system32\mmclv.dll

%WINDIR%\system32\mmcndmgr.dll

%WINDIR%\system32\mtxinfr1.dll

%WINDIR%\system32\mtxinfr2.dll

%WINDIR%\system32\mtxclu.dll

%WINDIR%\system32\mtxrn.dll

%WINDIR%\system32\mtxdm.dll

[すべて削除] オプションを実行するとユーザー定義パッケージが削除される

前のバージョンの MTS を使用していて、ユーザー定義パッケージを残す場合は、セットアップ プログラムの [すべて削除] オプションまたはコントロール パネルの [アプリケーションの追加と削除] アイコンを使わないでください。MTS を削除すると、すべてのユーザー定義パッケージが削除されます。アップグレードするときにユーザー定義パッケージを残すには、既存のバージョンの MTS に新しい MTS を上書きインストールしてください。

システム パッケージ ID のパスワードを間違えた場合

セットアップ時にシステム パッケージ ID のパスワードの指定を間違えると、Microsoft Transaction Server エクスプローラは動作しません。この場合は、カタログ サーバー (システム パッケージ) から 80008005 エラー (サーバー実行の失敗) が返されます。不正なパスワードを修正するには、Microsoft Transaction Server を再インストールします。

また、システム パッケージ ID のパスワードの指定を間違えると、パッケージが実行されず、同じ 80008005 エラーが発生します。ただし、この場合、クライアントは CoCreateInstance の失敗 HRESULT または同等の失敗と見なします。このエラーを修正するには、MTS エクスプローラに戻り、（パッケージの [プロパティ] ダイアログ ボックスの [ID] タブで) パッケージの ID を修正します。Windows NT のセキュリティ上の制約により、ユーザー ID は確認できますが、パスワードを確認することはできません。

Alpha プラットフォーム

Alpha AXP� コンピュータは MTS をサポートしています。ただし、Microsoft Transaction Server for Alpha platforms の今回のリリースには次のものが含まれていません。

•	Microsoft Visual J++ のコンポーネントとサンプル

Microsoft Visual C++ および Visual Basic のサンプル コンポーネントと管理オブジェクト サンプル スクリプトは、\Program Files\Mts\Samples フォルダにあります。

Alpha プラットフォームのサポートに関する最新情報については、http://www.microsoft.com/japan/products/ntserver/ を参照してください。

Alpha プラットフォームへの MTS のインストールの結果を確認するには、Alpha コンピュータ (サーバー） と x86 コンピュータ (クライアント) の 2 台のコンピュータを使って Sample Bank アプリケーションを実行します。詳細については、「Sample Bank アプリケーションのセットアップ」を参照してください。


開発者用サンプルとドキュメントのインストール

セットアップの [カスタム] オプションを使って Microsoft Transaction Server (MTS) の開発者用のサンプルとドキュメントをインストールできます。各セットアップ オプションでインストールされる MTS のコンポーネントは、次のとおりです。

•	最小セットアップ

MTS ランタイム環境と MTS エクスプローラをインストールします。

•	標準セットアップ

MTS ランタイム環境、MTS エクスプローラ、および MTS の主なドキュメントをインストールします。

•	カスタム セットアップ

MTS ランタイム環境、MTS エクスプローラ、MTS の主なドキュメント、MTS 開発者用サンプル、および MTS 開発者用ドキュメントをインストールします。

セットアップの [カスタム] オプションを使って MTS 開発者用サンプルとドキュメントをインストールすることを強くお勧めします。MTS 開発者用サンプルとドキュメントを利用することによって、管理の対象となるパッケージとコンポーネントをより深く理解することができます。たとえば、Sample Bank と Tic-Tac-Toe 開発者用サンプルを使って、MTS エクスプローラによるパッケージの配置と管理を練習できます。また、サンプル アプリケーションを使って、MTS のインストールが正しく完了したかどうかを確認することもできます。

MTS 開発者用ドキュメントでは、アクティブ化の設定やトランザクションのプロパティなど、コンポーネントをパッケージに組み込む方法を規定する際に設計上の注意点について説明しています。『Programmer's Guide』には、MTS プログラミングの概念 (共有状態など) の解説のほかに、Sample Bank アプリケーションをインストールし、構成する方法を示すチュートリアルが記載されています。

セットアップの [最小] オプションまたは [標準] オプションを使ってインストールした後に、MTS 開発者用サンプルとドキュメントを入手するには

1	[スタート] ボタンをクリックし、[設定] をポイントします。次に、[コントロール パネル] をクリックします。

2	[アプリケーションの追加と削除] アイコンをダブルクリックし、[Windows NT 4.0 Option Pack] をクリックします。次に、[追加と削除] をクリックします。

MTS を削除すると、ユーザー定義パッケージが削除されることに注意してください。ユーザー定義パッケージを残しておくには、前回インストールした MTS を削除せずに新しい MTS をインストールします。

3	セットアップ プログラムで [追加/削除] をクリックします。

4	[Microsoft Transaction Server] をクリックし、[サブコンポーネントの表示] をクリックします。

5	すべての MTS サブコンポーネントのチェック ボックスがオンになっていることを確認します。

6	[OK] をクリックします。


MTS サーバーの構成

MTS をインストールしたら、MTS エクスプローラを使って MTS パッケージを配置し、管理することができるように、MTS サーバーを構成します。パッケージの配置と管理を開始する前に、次の操作を実行して、MTS サーバーで配置を行うことができるように設定します。

•	システム パッケージのロールとパッケージ ID を構成する。

•	管理の対象となるコンピュータを設定する。

さらに、Windows NT ユーザー マネージャを使って、System パッケージおよびほかの MTS パッケージの ID に割り当てるユーザー アカウントが、Windows NT のユーザーの権利 "サービスとしてログオン" を持つことを確認します。

ユーザー アカウントの Windows NT ユーザーの権利を確認するには

1	ユーザー マネージャを起動し、[原則] メニューの [ユーザーの権利] をクリックします。

2	[高度なユーザー権利の表示] をオンにします。

システム パッケージのロールを構成する

MTS パッケージを安全に配置し、管理するには、システム パッケージの Administrator ロールに適切なユーザーを割り当てなければなりません。MTS がセットアップされたときは、システム パッケージの Administrator ロールにユーザーが割り当てられていません。したがって、システム パッケージのセキュリティは無効になっており、どのユーザーでも MTS エクスプローラを使ってそのコンピュータのパッケージの構成を変更することができます。ユーザーをシステム パッケージのロールに割り当てると、MTS はユーザーが MTS エクスプローラでパッケージを変更しようとしたときにロールをチェックします。

特に指定しなければ、システム パッケージには Administrator ロールと Reader ロールがあります。システム パッケージの Administrator ロールに割り当てられたユーザーは、MTS エクスプローラのすべての機能を使うことができます。Reader ロールに割り当てられたユーザーは、MTS エクスプローラの階層内のすべてのオブジェクトを表示することができますが、オブジェクトのインストール、作成、変更、削除やサーバー プロセスのシャットダウン、パッケージのエクスポートを行うことはできません。たとえば、自分の Windows NT ドメイン ユーザー名をシステム パッケージの Administrator ロールに割り当てると、MTS エクスプローラを使ってすべてのパッケージを追加、変更、または削除を行うことができます。プライマリ ドメイン コントローラまたはバックアップ ドメイン コントローラになっているサーバーに MTS がインストールされている場合、ユーザーが MTS エクスプローラでパッケージを管理するには、そのユーザーはドメイン管理者でなければなりません。

ユーザーをロールに割り当てる方法の詳細については、「MTS ロールをユーザーとグループにマップする」を参照してください。

システム パッケージに新しいロールを設定することもできます。たとえば、ユーザーにパッケージのインストールと実行を許可し、削除とエクスポートは許可しない Developer ロールを構成することができます。このロールに割り当てる Windows NT ユーザー アカウントまたはグループは、コンピュータに対する完全な管理者特権を持っていなくても、そのコンピュータでパッケージのインストールをテストすることができます。新しいロールの設定の詳細については、「新しい MTS ロールの追加」を参照してください。

コンピュータのシステム パッケージのロールを構成したら、パッケージの [プロパティ] ダイアログ ボックスの [セキュリティ] タブのチェック ボックスをオンにして認証の確認を有効にします。認証の確認を有効にする方法の詳細については、「MTS パッケージ セキュリティを有効にする」を参照してください。

次の MS DTC 管理機能では、システム パッケージまたはシステム パッケージのロールが使用されないことに注意してください。

•	[トランザクションの統計] ウィンドウ

•	[トランザクションの一覧] ウィンドウ

•	[トレース メッセージ] ウィンドウ

•	[MS DTC 開始] コマンドおよび [MS DTC 停止] コマンド

MTS エクスプローラを使って管理できるようにコンピュータを設定する

MTS をインストールしたコンピュータは MTS エクスプローラで "マイ コンピュータ" として管理されます。MTS エクスプローラを使ってほかのコンピュータを管理することもできます。MTS エクスプローラで [コンピュータ] フォルダを選択し、次のいずれかの操作を実行すると、管理する必要がある新しいコンピュータを [コンピュータ] フォルダに追加できます。

•	[動作] メニューの [新規作成] をポイントし、[コンピュータ] をクリックします。

•	MTS エクスプローラのツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

•	マウスの右ボタンで [コンピュータ] フォルダをクリックし、[新規作成] をポイントします。次に、[コンピュータ] をクリックします。

次に、表示されるダイアログ ボックスで Windows NT ドメインでのコンピュータ名を入力してリモート コンピュータを最上位のフォルダとして追加します。リモート サーバーにアクセスして MTS エクスプローラを表示するには、ログオン アカウントが Reader ロールに割り当てられている必要があります。MTS エクスプローラがリモート サーバーに対して完全な読み取り/書き込み権限を持つには、ログオン アカウントが Administrator ロールにマップされていなければなりません。

MTS エクスプローラの階層内のオブジェクトを管理する方法の詳細については、「MTS エクスプローラの階層」を参照してください。

重要   Windows 95/98 コンピュータ上の MTS を Windows NT サーバー上の MTS からリモートで管理することはできません。


MTS を Microsoft Cluster Server と組み合わせて使うように構成する

Microsoft Cluster Server (MSCS) は Windows NT Server を実行しているコンピュータのクラスタ化を行います。MSCS Version 1.0 は、Windows NT Server を実行している特別にリンクされた 2 台の サーバーをクラスタ化します。クラスタの一方のサーバーが故障したり、オフラインになったりすると、もう一方のサーバーが故障したサーバーの動作を引き継ぎます。

Microsoft Transaction Server を MSCS と組み合わせて使うには、まず Windows NT Server 4.0 Enterprise Edition をインストールします。次に、Microsoft Cluster Server 1.0 をインストールします。最後に、次の手順に従って Microsoft Transaction Server 2.0 をインストールします。

注   MTS 2.0 は、Microsoft Cluster Server 1.0 のプレリリース版と組み合わせて使うことはできません。MTS 2.0 を Microsoft Cluster Server のプレリリース版と共にインストールすると、MSCS は正しく動作しません。

MSCS の詳細については、Windows NT のオンライン ブックを参照してください。

 Microsoft Cluster Server 1.0 と共に Microsoft Transaction Server 2.0 をインストールするには

1	Windows NT Server 4.0 Enterpirse Edition をインストールします。

2	クラスタ内のすべてのコンピュータに MSCS 1.0 をインストールします。

3	MSCS クラスタ アドミニストレータを使って、ネットワーク名リソースと共有ディスク リソースを含むグループを構成します。

4	手順 3 で構成したグループを所有するノードに Microsoft Transaction Server 2.0 をインストールします。詳細については、「セットアップ」を参照してください。

5	MTS セットアップがシステム上に MSCS があることを検出すると、MS DTC のインストール先の仮想サーバー名を指定するように求めるダイアログ ボックスが表示されます。手順 3 で構成したネットワーク名リソースの名前を指定します。

6	同じダイアログ ボックスで、手順 3 で構成した共有ディスク上の MS DTC ログ ファイルの場所を指定します。

7	[次へ] をクリックして MTS セットアップを継続します。

8	クラスタの 2 つめのコンピュータに MTS をインストールします。セットアップ中に仮想サーバーとログ ファイルの場所を指定するように求めるダイアログ ボックスは、表示されません。

2 つのクラスタ ノードで並行して MTS セットアップを実行しないでください。1 つのノードに MTS を完全にインストールし、最初のノードを再起動せずに 2 つめのノードに MTS をインストールします。両方のノードに MTS をインストールしたら、両方のノードを再起動します。

注   Microsoft Transaction Server 2.0 を Microsoft Cluster Server 1.0 と一緒にインストールする前に、Microsoft Transaction Server 1.0 を削除する必要はありません。MTS 2.0 を MSCS 1.0 と一緒にインストールときの手順に従って操作してください。

 Microsoft Transaction Server 1.1 と Microsoft Cluster Server の組み合わせから Microsoft Transaction Server 2.0 と Microsoft Cluster Server の組み合わせにアップグレードするには

1	Microsoft Transaction Server 1.1 を Microsoft Cluster Server と組み合わせて使っていたときに作成した Microsoft Transaction Server パッケージ リソースをすべて削除します。

2	MS DTC のリソースを所有するクラスタ ノードで Microsoft Transaction Server 2.0 のセットアップ プログラムを実行します。そのノードで自動的にアップグレードが実行されます。次の手順に進む前に、Microsoft Transaction Server のセットアップが完了していることを確認してください。

3	クラスタの 2 つめのノードで Microsoft Transaction Server 2.0 のセットアップ プログラムを実行します。

4	両方のクラスタ ノードを再起動します。

MTS サーバーの Microsoft Cluster Server を削除する

クラスタのノードの 1 つから Microsoft Cluster Server を削除する場合は、次の手順に従って操作します。

1	クラスタ アドミニストレータを使って MS DTC のリソースをオフラインにします。

2	ノードから Microsoft Cluster Server を削除し、ノードを再起動します。

3	Transaction Server エクスプローラを使って、MS DTC のログ ファイルの場所を変更します。ログ ファイルは非共有ディスクに置かなければなりません。非共有ディスクに置かないと、ログ ファイルが壊れたり、MS DTC のアクセス違反が発生したりすることがあります。

クラスタ サーバーの MS DTC ログ ファイルをリセットする

クラスタ サーバーの MS DTC ログ ファイルをリセットするには、ログ ファイルを含む共有ディスクを現在所有しているノードで MTS エクスプローラを実行しなければなりません。

クラスタ サーバーで MS DTC を開始または停止する

MTS エクスプローラまたは MSCS 管理ユーティリティのいずれかを使用して、クラスタ サーバーで MS DTC を開始または停止できます。"net start msdtc" コマンドまたは "net stop msdtc" コマンドは機能しません。コマンド ラインから MSCS クラスタの MS DTC を開始または停止するには、"msdtc -start" と "msdtc -stop" を使います。

MSCS のフェールオーバー後に MTS オブジェクトを呼び出す

Microsoft Transaction Server クライアント アプリケーションは、必ず、障害が発生したノードの MTS コンポーネントへの参照をすべて解放し、コンポーネントのインスタンスを再生成しなければなりません。コンポーネントのインスタンスは 2 つめのノードで生成されます。

クラスタ サーバーと組み合わせて [リモート コンポーネント] フォルダを使う

[リモート コンポーネント] フォルダを使って Microsoft Cluster Server (MSCS) のノードからコンポーネントをプルするには、次の手順に従って操作します。

1	コンポーネントをプルするサーバー コンピュータで、[マイ コンピュータ] アイコンをマウスの右ボタンでクリックし、[プロパティ] をクリックします。

2	[オプション] タブをクリックし、仮想サーバーの名前を [リモート サーバー名] ボックスに入力します。次に、[OK] をクリックします。

3	プルしたコンポーネントの移動先クライアント コンピュータで、サーバーの物理名を使って MSCS コンピュータを [コンピュータ] フォルダに追加します。

4	次のいずれかの方法で、リモート コンポーネントを追加します。

•	[リモート コンポーネント] フォルダを選択し、[動作] メニューの [新規作成] をポイントします。次に、[リモート コンポーネント] をクリックします。

•	[リモート コンポーネント] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[リモート コンポーネント] をクリックします。

5	[リモート コンポーネント] ダイアログ ボックスでインストールするコンポーネントを選択します。リモート コンポーネントのインストール中は、(サーバー コンピュータの [リモート サーバー名] ボックスで指定した) サーバーの仮想名でなく、物理名が表示されることに注意してください。

6	[リモート コンポーネント] フォルダを選択し、MTS エクスプローラ ツール バーの [プロパティ表示] ボタンをクリックします。プロパティ表示のウィンドウの [サーバー] 列に仮想サーバー名が表示されます。

注   MSCS コンピュータのリモート サーバー名を変更した場合は、クライアント コンピュータにリモート コンポーネントを再インストールしなければなりません。

空のパッケージのレプリケーション

MTS のレプリケーションでは、空のパッケージはレプリケートできません。

MTS パッケージ ID は MSCS クラスタの Administrator グループに属していなければならない

MSCS クラスタ上の MTS パッケージの場合、パッケージ ID に対応するユーザー アカウントは、システム管理者であるか、または (cluadmin で設定した) Full Control クラスタ アクセス権限を持っている必要があります。システム管理者の ID の元でパッケージを実行しなかった場合は、MTS は MS DTC に接続できません。

MTS をインストールする前に MSCS クラスタをシャットダウンする

MTS セットアップ プログラムを実行する前に、MTS セットアップが影響を与える (SQL Server などの) すべての MSCS クラスタ リソースをシャットダウンする必要があります。

MSCS サーバーでは リモート サーバー名に仮想サーバーを指定しなければならない

クラスタ サーバーでは、MTS エクスプローラを使って [リモート サーバー名] プロパティに仮想サーバー名を指定する必要があります。これによって、リモート クライアントはクラスタ内の MTS コンポーネントにアクセスできます。失敗した場合、クライアントはクラスタの特定のノードではなくクラスタを参照します。


MTS を Oracle にアクセスできるように設定する

Microsoft Transaction Server コンポーネントは、次のリソースにアクセスできます。

•	Oracle 7 および Oracle 8 データベース

•	Windows NT および Unix システム上の Oracle データベース

•	Oracle Workgroup Servers

•	Oracle Enterprise Servers

•	Oracle Parallel Servers

ここでは、次のトピックについて説明します。

必要なソフトウェア

Oracle サポートを設定する

インストールをテストして MTS の Oracle サポートを構成する

Sample Bank アプリケーションを使って Oracle のインストールと構成を確認する

Oracle および Microsoft 分散トランザクション コーディネータを管理する

MTS の Oracle サポートに関する既知の制限事項

必要なソフトウェア

Microsoft Transaction Server コンポーネントから Oracle データベースをアクセスするには、次のソフトウェアが必要です。

コンポーネント	バージョン
Windows NT 上の Oracle データベース	7.3.4 または Oracle 8
Unix 上の Oracle データベース	現バージョンとパッチ、または Oracle 8
Microsoft Transaction Server 2.0	2.0
Microsoft Oracle ODBC Driver 2.0	02.73.7283.1 以降
ActiveX Data Objects (ADO)	1.5 以降
重要: ソフトウェアの以前のバージョンは、正しく動作しません。必ず、前の表で示したバージョン (または以降のバージョン) のソフトウェアをインストールしてください。Microsoft Transaction Server を Oracle とともに使用する場合に発生する問題の原因は、多くの場合この点にあります。

Windows NT 上の Oracle 7.3 データベース

MTS のトランザクション コンポーネントは、Windows NT 上の Oracle 7.3 データベースにアクセスできます。Oracle 7.3.4 Workgroup Server release for Windows NT または Oracle 7.3.4 Enterprise Server release for Windows NT を使用できます。これより前のリリースは、MTS トランザクションと共に使用することはできません。

Windows NT 上の Oracle 8 データベース

MTS のトランザクション コンポーネントは、Windows NT 上の Oracle 8 データベースにアクセスできます。

Oracle 7.3.4 クライアント ソフトウェアを MTS コンポーネントがあるシステムにインストールする必要があります。Microsoft Oracle ODBC Driver 2.0 だけが、Oracle 7.3 クライアント インターフェイスと共に使うことができます。Oracle 8 クライアント インターフェイスと共に使用することはできません。

Oracle 8 のドキュメントでは、Oracle 8 を Oracle 7 クライアント ソフトウェアと共存するようにインストールして設定する方法が説明されています。詳細については、Oracle 8 のドキュメントを参照してください。

UNIX 上の Oracle 7 データベース

MTS トランザクション コンポーネントは、UNIX 上の Oracle 7.3 データベースをアクセスできます。

使用する UNIX プラットフォーム用の Oracle 7.3.3 release 以降をインストールする必要があります。ほとんどの場合、Oracle 7.3.3 patch release for Oracle on UNIX もインストールする必要があります。

使用する UNIX プラットフォームで Oracle 7.3.3 patch release が必要かどうかは、Oracle カスタマ サポートに確認する必要があります。Oracle 7.3.4 release on Windows NT が提供する XA トランザクション サポート機能を使って、UNIX 上の Oracle データベースをアクセスしようとしていることを説明してください。

UNIX 上の Oracle 8 データベース

MTS トランザクション コンポーネントは、UNIX 上の Oracle 8 データベースをアクセスできます。

Oracle 7.3.4 クライアント ソフトウェアを、MTS コンポーネントがある Windows NT システムにインストールする必要があります。Microsoft Oracle ODBC Driver 2.0 のみ、Oracle 7.3 クライアント インターフェイスと共に使用できます。これは、Oracle 8 クライアント インターフェイスと共に使用することはできません。

Oracle クライアント ソフトウェア

Oracle 7.3.4 クライアント ソフトウェアを、MTS コンポーネントがある Windows NT または Windows 95/98 システムにインストールする必要があります。Microsoft Oracle ODBC Driver 2.0 のみ、Oracle 7.3 クライアント インターフェイスと共に使用できます。これは、Oracle 8 クライアント インターフェイスと共に使用することはできません。

Oracle OCIW32.DLL

Oracle 7.3 release と共に使用できる Oracle OCIW32.DLL の指定されたバージョンをシステムにインストールする必要があります。この DLL は、Oracle 7.3 CD の "WIN32\V7\RSF73" ディレクトリにあります。

Oracle 7.3 CD には、OCIW32.DLL の古いバージョンも含まれています。この DLL は Oracle 7.2 release に対応し、"WIN32\V7\RSF72" ディレクトリに含まれています。この DLL を MTS と共に使用することはできません。

Oracle OCIW32.DLL の次のバージョンは "WIN32\V7\RSF72" ディレクトリにあり、MTS と共に使用すると失敗することが知られています。

Version 7.x

Thursday, February 01, 1996 12:50:06 AM

Size 36 KB

Oracle XA73.DLL

Oracle XA73.DLL の指定されたバージョンを、MTS システムにインストールする必要があります。

Microsoft Transaction Server 2.0

MTS トランザクション コンポーネントを使って Oracle データベースにアクセスするには、Microsoft Transaction Server 2.0 をインストールする必要があります。

Microsoft ODBC Driver for Oracle

MTS トランザクションを使用するには、Microsoft ODBC Driver 2.0 for Oracle (MSORCL32.DLL) version 02.73.7283.1 以降が必要です。Windows NT 4.0 Option Pack セットアップ プログラムは、この DLL を自動的にインストールします。

Oracle データベースにアクセスする場合、トランザクション サポートが必要ない場合でも新しい Microsoft Oracle ODBC Driver 2.0 を使用することを強く推奨します。この新しいドライバは、Oracle 1.0 ドライバよりも高いパフォーマンスを提供します。Oracle 1.0 ドライバは、すべてのアクティビティをドライバ レベルでシリアル化し、要求はドライバを介してシングルスレッド化されます。Oracle 2.0 ドライバは、すべてのアクティビティを接続レベルでシリアル化します。これによって、異なるデータベース接続を同時に使用できます。

ActiveX Data Objects (ADO)

アプリケーションが ADO を使用する場合、ADO version 1.5 をインストールする必要があります。それ以前の ADO のリリースは、新しい ODBC 3.5 Driver Manager とともに使用することができません。ADO 1.5 は、Windows NT 4.0 Option Pack で提供されます。

Oracle サポートを設定する

 MTS のトランザクション コンポーネントを Oracle がサポートするように設定するには

1	Oracle Database Server ソフトウェアのインストール

既に説明したように、適切な Oracle ソフトウェアをデータベース サーバー システムにインストールします。

2	Oracle クライアント ソフトウェアのインストール

Oracle 7.3.4 クライアント ソフトウェアを MTS システムにインストールします。

「必要なソフトウェア」の表に記載された正しいバージョンの Oracle OCIW32.DLL がインストールされていることを確認します。

3	Microsoft Transaction Server 2.0 のインストール

Microsoft Transaction Server 2.0 をインストールすると、次のソフトウェアがインストールされます。

・ Microsoft Transaction Server 2.0 (Microsoft OCI Interface を含む)

・ Microsoft ODBC 3.5 Driver Manager

・ Microsoft ODBC Driver for Oracle 2.0

・ ADO 1.5

4	DTCXATM.LOG の削除

Microsoft Transaction Server 2.0 のベータ版をインストールしていない場合は、次のステップに進んでください。

Microsoft Transaction Server 2.0 のベータ版をインストールしている場合は、Windows エクスプローラを使って DTCXATM.LOG ファイルがシステムにあるかどうかを確認します。もしあれば、MS DTC サービスを停止して DTCXATM.LOG ファイルを削除します。

DTCXATM.LOG ファイルを削除しなければならないのは、Microsoft Transaction Server 2.0 ベータ版からアップグレードするときだけです。DTCXATM.LOG ファイルは修復に必要な重要な情報を含んでいる可能性があるので、これ以降は絶対に DTCXATM.LOG ファイルを削除しないでください。

5	Oracle XA トランザクション サポートを有効にします。

Oracle XA トランザクション サポートを有効にするには、次の操作を行います。

1	Oracle システム管理者は V$XATRANS$ というビューを作成しなければなりません。ビューを作成するには、Oracle が提供するスクリプト "xaview.sql" を実行する必要があります。このファイルは、通常 C:\ORANT\RDBMS73\ADMIN にあります。

2	システム管理者は、これらのビューを選択 (SELECT) する権限を Public ユーザーに与えなければなりません。

Grant Select on V$XATRANS$ to public.

3	Oracle Instance Manager で [表示] メニューの [拡張モード] をクリックし、ウィンドウの左側の [初期化パラメータ] を選択します。ウィンドウの右側で [拡張チューニング] を選択し、"distributed_transactions" パラメータをの値を増やすと、より多くの MTS 同時実行トランザクションが同時にデータベースを更新できるようになります。

Oracle の XA トランザクション サポートを構成する方法については、Oracle Server のドキュメントを参照してください。

統合セキュリティの構成

統合セキュリティによって、Oracle データベースは、データベース ユーザーを確認するために Windows NT の認証を利用することができます。これによって、ユーザーは別のログイン ID またはパスワードを指定しなくても Oracle データベースにログインできます。ユーザーは、Windows NT および Oracle データベースの両方に対してログイン ID とパスワードを １ つだけ保持すればよいわけです。

Oracle データベースに接続するときに、MTS コンポーネントが常にログイン ID とパスワードを指定する場合は、統合セキュリティは使用しません。アプリケーションが DSN を介して、直接的または間接的にログイン ID およびパスワードを指定する場合が該当します。いずれの場合も、統合セキュリティを使わないので、このステップは必要ありません。

統合セキュリティを使う場合、Oracle データベースに接続するために認証されたログイン ID およびパスワードのもとで実行するように MS DTC を構成しなければなりません。これは、データベースを回復する間に、MS DTC は Oracle データベースを開き、イン ダウトのトランザクションの結果を報告しなければならないからです。

次の手順で MS DTC のログイン ID を設定できます。[スタート] メニューの [設定] をポイントして [コントロール パネル] を選択します。次にコントロール パネルの [サービス] を開始します。一覧の [MSDTC] をダブルクリックします。[ログオン] の [アカウント] を選択して、ログイン ID とパスワードを指定します。Oracle のセキュリティ管理ツールを使って、指定したログイン ID が Oracle データベースを開けるように認証されていることを確認します。

Windows NT セキュリティ機能を統合した Oracle データベースについては、Oracle のドキュメントを参照してください。

より多くの接続をサポートするように Oracle を構成する

Oracle データベースに対する接続を数十以上作成するには、さらに多くのデータベース接続をサポートするように Oracle サーバーを構成する必要があります。詳細については、「多くの接続をサポートするように Oracle を構成する」を参照してください。

インストールをテストして MTS の Oracle サポートを構成する

Oracle サポートをインストールして構成したら、MTS とともにインストールされる Oracle テスト プログラムを使って Oracle インストールを確認する必要があります。Oracle テスト プログラムは、MTS が Oracle の OCI XA インターフェイスを使用するのと同様の方法で、これらを使用します。

Oracle テスト プログラムは、Oracle の XA 機能を使って Oracle データベースに接続できるかどうかを判断します。Oracle テスト プログラムは、標準の Oracle インターフェイスとトランザクション機能を使用します。Microsoft Transaction Server または Microsoft 分散トランザクション コーディネータは使用しません。したがって、テスト プログラムの失敗は、Oracle システムが正しくインストールされていないか、または正しく構成されていないことを示します。Oracle テスト プログラムが失敗した場合は、Oracle を再度インストールして構成しするか、Oracle のサポート部門に問い合わせてください。

 Oracle テスト プログラムを実行するには

1	「必要なソフトウェア」で説明されているように、正しいバージョンのソフトウェアがインストールされていることを確認します。

2	Oracle データベースを参照する ODBC DSN を作成します。DSN が、新しい Microsoft Oracle ODBC 2.0 ドライバを使用するようにします。

3	Oracle XA サポートを使用できるようにします。

4	既存のすべての Oracle トレース ファイルを、Oracle データベースをアクセスする MTS コンポーネントがあるコンピュータから削除します。もっとも容易な方法は、Windows エクスプローラを使って *.TRC ファイルがある場所を確認し、すべて削除することです。
Oracle テスト プログラムが失敗した場合、問題の原因を判断するためにトレース ファイルが役立つ場合があります。すべてのトレース ファイルを完全に削除することで、新たに作成されたファイルを容易に見つけることできます。

5	Microsoft Transaction Server 2.0 ベータ版をインストールした場合は、Windows エクスプローラを使って DTCXATM.LOG ファイルがシステムにあるかどうかを確認します。もしあれば、MS DTC サービスを停止して DTCXATM.LOG ファイルを削除します。
Microsoft Transaction Server 2.0 ベータ版をインストールしてない場合は、次のステップに進んでください。
DTCXATM.LOG ファイルを削除しなければならないのは、Microsoft Transaction Server 2.0 ベータ版からアップグレードするときだけです。DTCXATM.LOG ファイルは回復に必要な重要な情報を含んでいる可能性があるので、これ以降は絶対に DTCXATM.LOG ファイルを削除しないでください。

6	MS-DOS コマンド プロンプトから Oracle テスト プログラム (TestOracleXaConfig.exe) を実行して、次の例のように Oracle サーバーのユーザー ID、パスワード、およびサービス名を指定します。

c:>TestOracleXaConfig.exe  -U<user id> -P<Password>

-S<Service_Name as contained in the TNS file>.

パラメータを指定しないでテスト プログラムを実行すると、必要なパラメータに関するヘルプ情報が表示されます。
テスト プログラムは、実行される Oracle の各操作に関する情報およびどの操作が成功したかを表示します。

7	Oracle テスト プログラムがエラーを起こさずに Oracle データベースに接続できれば、MTS は Oracle とともに実行できると考えられます。Oracle テスト プログラムがエラーを報告した場合は、次のいずれかの作業を行います。

•	Oracle テスト プログラムが表示したエラー メッセージを正確に記録します。

•	Oracle テスト プログラムの実行中に生成された Oracle トレース ファイルを調査します。Oracle トレース情報は、*.TRC ファイルにあります。Oracle トレース ファイルは、問題を診断するのに大変役立つ情報も含んでいます。

•	Oracle のサポート部門に問い合わせます。

Sample Bank アプリケーションを使って Oracle のインストールと構成を確認する

Oracle テスト プログラムを使って Oracle のインストールと構成を確認したら、Microsoft Transaction Server とともに提供される Sample Bank アプリケーションを使って、Microsoft Transaction Server が Oracle データベースにアクセスできるかどうかを確認する必要があります。

 Sample Bank を使って Oracle サポートを確認するには

1	MTS で提供される Oracle テスト プログラムを使って、Oracle システムが正しくインストールされて構成されているかを確認します。Oracle テスト プログラムが何らかのエラーを報告した場合は、次に進む前に修正しなければなりません。

2	Oracle データベース サーバーで "Account" という名前のテーブルを作成します。次の例は、Account テーブルの設定を示します。

所有者	scott

テーブル名	Account

列 1 の名前	AccountNo	(タイプは NUMBER)

列 2 の名前	Balance	(タイプは NUMBER)

3	"Account" テーブルに少なくとも 2 行のレコードを作成します。次の表は、テーブルに読み込むレコードを示します。

AccountNo	Balance

1	1000

2	1000

4	Oracle データベース サーバーで "Receipt" という名前のテーブルを作成します。次の例は、Receipt テーブルの設定を示します。

所有者	scott

テーブル名	Receipt

列 1 の名前	NextReceipt	(タイプは NUMBER)

5	"Receipt" テーブルに少なくとも 1 行のレコードを作成します。次の表は、テーブルに読み込むレコードを示します。

NextReceipt

1000

6	ODBC 構成ユーティリティを使って、ファイル DSN を作成します。ファイル DSN の名前は、"MTSSamples" です。次に、ファイル DSN を手作業で更新して、ユーザーのパスワードを追加します。次の例は、ファイル DSN にユーザー パスワードを追加する方法を示します。

[ODBC]

DRIVER=Microsoft ODBC for Oracle

UID=scott

PWD=mypassword

ConnectString=myserver

SERVER=myserver

7	ファイル DSN を保存し、Sample Bank クライアントを実行します。

Oracle と Microsoft 分散トランザクション コーディネータの管理

Oracle の将来のリリースでの DLL 名の変更

Oracle は製品の新しいバージョンがリリースされると、DLL 名を変更することがあります。MTS は、いくつかの Oracle DLL の既知の名前を使用します。現在、MTS は Oracle 7.3 release の DLL 名を検索します。Oracle がこれらの DLL の名前を変更した場合は、次のレジストリ キーの値を変更する必要があります。

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

次のキーの下には、2 つの文字列名値があります。

•	OracleXaLib	"xa73.dll"

•	OracleSqlLib	"sqllib18.dll"

MS DTC を実行するユーザー ID の変更

Microsoft 分散トランザクション コーディネータ (MS DTC) は、NT レジストリの保護された部分の情報を保守します。これらの情報は、Oracle が提供する XA 互換データベースを回復するときに使われます。MS DTC を実行するユーザー ID を変更した場合、レジストリの保護された部分に MS DTC が格納した情報を、MS DTC がアクセスできることを注意して確認してください。

MS DTC のユーザー ID を変更し、保護されたレジストリの情報にアクセスできなくなった場合、次のメッセージが Windows NT イベント ログに記録されます。

XATM log object failed to set log encryption key

この問題は、次の手順で解決できます。

1	MS DTC を停止します。

2	MS DTC のユーザー ID を前の値に戻します。代わりに、管理者グループのメンバーのユーザー ID を割り当てることもできます。ユーザー ID およびパスワードを変更するには、コントロール パネルの [サービス] を実行して、一覧の [MSDTC] をダブルクリックします。[ログオン] の [アカウント] の値を変更します。

3	MS DTC を再開します。

多くの接続をサポートするように Oracle を構成する

Oracle データベースに対する接続を数十以上作成するには、さらに多くのデータベース接続をサポートするように Oracle サーバーを構成する必要があります。

これを行わないと、次のいずれかのエラーが発生する可能性があります。

•	SQLConnect 呼び出しの失敗

•	オブジェクト トランザクションの呼び出しでエンリストに失敗する。この問題が発生した場合、Oracle トレース ファイルに次のいずれかのエラーの結果が記録されている可能性があります。

•	セッションが多すぎる

•	TNS サーバーがサーバー名の検索に失敗した

•	分散トランザクションが多すぎる

•	データベース ロックを待っている間にタイムアウトになりました。これは、設定されたロック数が、同時実行されるアクティブ トランザクション数より不足していることが考えられます。

•	イン ダウト トランザクションが起こしたロックによって、レコードが衝突しました。

これらの問題が発生した場合には、次の Oracle サーバー構成パラメータの値を増やします。

Oracle 構成パラメータ

sessions

distributed_lock_timeout

distributed_transactions

dml_locks

max_transaction_branches

open_cursors

processes

queuesize

Sessions

sessions の値は、通常、アプリケーションが作成すると予想されるデータベース接続の総数の 3 倍の数でなければなりません。

Queuesize

Oracle Listener プロセスに対するキュー サイズが適切でない場合、Listener は処理が間に合わなくなりデータベースを開く要求を拒否することがあります。これは、Oracle Listener が多すぎる接続要求を受け取り、キューがオーバーフローする場合に、発生します。このエラーを検出したクライアントは、メッセージ "ORA-12541: No Listener" を返し、クライアント ログまたはトレース ファイルが EDONREFSED メッセージを表示します。

  接続要求の問題を解決するには

1	Oracle データベース サーバーを含むシステムの Oracle Listener を停止します。

2	Oracle データベース サーバー システム上の LISTENER.ORA、TNSNET.ORA、または NAMES.ORA ファイルの QUEUESIZE パラメータの値を増やします。参加する接続要求と同じ、または近い値を基にキュー サイズを選択します。
QUESIZE には大きめの値を設定することをお勧めします。これは、Oracle システムが、通常、アプリケーションが開く各トランザクション データベース接続に対して、2 つ以上のデータベース接続を開くからです。結果として、Oracle Listener のキューは、いっぱいになりオーバーフローします。
たとえば、100 の接続要求に対応できるようにするには、LISTENER.ORA ファイルを次のように変更します。

QUEUESIZE = 100

3	Oracle Listener を再開します。

MTS の Oracle サポートに関する既知の制限事項

ODBC 3.5 を使用するには ADO 1.5 が必要

アプリケーションが ADO を使用する場合、必ず ADO 1.5 をインストールしてください。詳細については、「必要なソフトウェア」を参照してください。

Oracle は DEC 社の Alpha プラットフォームをサポートしない

Oracle データベース接続は、Microsoft Transaction Server を実行する Alpha プラットフォームではサポートされません。DEC 社の Alpha プラットフォームでの Oracle サポートは、将来のリリースで実現されます。

Oracle OCIW32.DLL のバージョンの問題

OCIW32.DLL の正しいバージョンをコンピュータにインストールすることが、重要です。Oracle または Microsoft Transaction Server を再インストールする場合は、必ず DLL のバージョンを確認してください。

Oracle の将来のリリースでの DLL 名の変更

Oracle は製品の新しいバージョンがリリースされると、DLL 名を変更することがあります。MTS は、いくつかの Oracle DLL の既知の名前を使用します。現在、MTS は Oracle version 7.3.3 の DLL 名を検索します。MTS はこれらの DLL の将来の名前を予想できないので、Oracle をアップグレードしたときには次のレジストリの値を変更しなければならない場合があります。

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

次のキーの下には、2 つの文字列名値があります

•	OracleXaLib	"xa73.dll"

•	OracleSqlLib	"sqllib18.dll"


Sample Bank アプリケーションのセットアップ

Sample Bank アプリケーションは、入金、出金、および振り替えを行う銀行サービス業務アプリケーションです。Sample Bank アプリケーションを実行すると、MTS と SQL Server 6.5 を組み合わせたインストールの結果、および練習用パッケージの配置と管理をテストすることができます。Sample Bank には、Visual Basic、Visual C++、および Visual J++ で記述されたコンポーネントが含まれます。Sample Bank は \Program Files\Mts\Samples ディレクトリにあります。

『Programmer's Guide』には、Sample Bank コンポーネントを作成する方法を詳しく説明するチュートリアルが記述されています。

Sample Bank アプリケーションを実行するには、次の作業をを行わなければなりません。

•	セットアップの [カスタム] オプションを選択し、すべての MTS サブコンポーネントを選択します。詳細については、「開発者用サンプルとドキュメントのインストール」を参照してください。

•	DSN を設定する。

•	Sample Bank パッケージをインストールする。

•	MTS エクスプローラで Sample Bank パッケージを監視できるように設定する。

•	Bank クライアントを実行する。

Sample Bank アプリケーションを設定する

MTS はセットアップ中に自動的に Sample Bank の ODBC データ ソースを構成します。既定の設定でローカル マシンが使用されるので、ローカル マシンに SQL Server 6.5 をインストールしておかなければなりません。

既定の設定では、MTS DSN は SQL Server 6.5 を指します。SQL Server 6.5 以外のデータベースを使用している場合は、DSN を削除し、使用しているデータベースを指す MTSSamples という新しい DSN を追加しなければなりません。

ほかのコンピュータにインストールされている SQL Server を使う場合は、コントロール パネルの [ODBC] アイコンを使ってデータ ソースを次の手順で変更します。

•	[ODBC データ ソース アドミニストレータ] ダイアログ ボックスで [ファイル DSN] タブをクリックし、MTSSamples データ ソースを選択します。

•	[構成] をクリックし、使用するサーバーの名前を入力します。

MTSSamples.dsn で指定されているログイン ID とパスワードは、Sample Bank では使われないことに注意してください。Sample Bank では "sa" というアカウントと null パスワードが使用されます。システム管理者のパスワードが null でない場合、または別のログイン ID を指定する場合は、Sample Bank のソース コードの ODBC 接続文字列を変更する必要があります。

Sample Bank パッケージのコンポーネントとトランザクションを監視するには

1	MTS エクスプローラのウィンドウの右側で、[Sample Bank] アイコンをダブルクリックします。

2	[コンポーネント] フォルダをダブルクリックします。

3	[表示] メニューの [状態] をクリックしてパッケージのさまざまなコンポーネントの使用状況に関する情報を表示します。

4	[ウィンドウ] メニューの [新しいウィンドウを開く] をクリックします。

5	2 つのウィンドウが重ならないように、新しいウィンドウの位置を調整します。[ウィンドウ] メニューの [重ねて表示] または [上下に並べて表示] をクリックして、ウィンドウを整列することもできます。

6	新しいウィンドウの左側で、[トランザクションの統計] をクリックします。

7	[動作] メニューの [スコープ ウィンドウ] をクリックしてウィンドウの左側を非表示にします。ウィンドウの左側が表示されているときは、このコマンドにチェック マークが付いています。トランザクション コンポーネントが使用されると、トランザクション統計情報が表示されます。

Bank クライアントを実行するには

1	Microsoft 分散トランザクション コーディネータ （MS DTC) が動作していることを確認します。Transaction Server エクスプローラのウィンドウの左側で [マイ コンピュータ] を選択します。[動作] メニューの [MS DTC 開始] が表示されていれば、このコマンドをクリックします。

2	SQL Server が動作していることを確認します。SQL Server はコントロール パネルで起動できます。

3	[スタート] ボタンをクリックし、[プログラム] をポイントします。次に、[Windows NT 4.0 Option Pack] をポイントし、[Microsoft Transaction Server] をポイントして [Bank クライアント] をクリックします。Bank クライアントのウィンドウが MTS エクスプローラのウィンドウと重ならないように、Bank クライアントのウィンドウの位置を調整します。

4	フォームは、口座番号 (Account Number) 1 へ 1 ドル入金 (Credit) するようにあらかじめ設定されています。[Submit] をクリックします。残高が変わることが確認できます。

5	MTS エクスプローラのウィンドウの表示に注意してください。コンポーネント使用状況とトランザクション統計情報の表示が更新されていることがわかります。

6	トランザクションの種類、サーバー、および繰り返し (Iterations) のさまざまな設定を使って Bank クライアントを実行し、統計情報を確認してください。次の理由により、最初のトランザクションでは 2 回目以降のトランザクションより時間がかかります。

•	最初のトランザクションでは Sample Bank のデータベース テーブルが作成され、一時的なレコードが挿入される。

•	サーバー プロセスの開始は、システム リソースを消費する。

•	最初のデータベース接続の開始は、サーバーにとって負荷が重い操作である。


Tic-Tac-Toe サンプル アプリケーションのセットアップ

Tic-Tac-Toe サンプル アプリケーションは、コンピュータまたはリモートの MTS コンピュータ上のほかのユーザーと対戦するゲームです。Tic-Tac-Toe アプリケーションを実行すると、SQL Server をインストールせずに MTS をインストールした結果、および練習用パッケージの配置と管理をテストすることができます。Tic-Tac-Toe サンプル アプリケーションは \Program Files\Mts\Samples ディレクトリにあります。

Tic-Tac-Toe サンプル アプリケーションを実行するには、次の作業を行う必要があります。

•	Microsoft Transaction Server をインストールする。

•	Tic-Tac-Toe クライアントを実行し、コンピュータまたはほかのユーザーと対戦する。

Tic-Tac-Toe クライアントを起動するには

1	[スタート] ボタンをクリックし、[プログラム] をポイントします。次に、[Microsoft Transaction Server] をポイントし、[Tic-Tac-Toe クライアント] をクリックします。

2	[Your Name is] ボックスに自分の名前を入力し、コンピュータ (Deep Viper) またはほかのユーザーを対戦相手として選びます。リモートのユーザーと対戦する方法については、「リモート MTS コンピュータを使う」を参照してください。

ゲームを開始したら、MTS エクスプローラに戻ります。Tic-Tac-Toe サーバー コンポーネントのアイコンが回転していることに注意してください。アイコンの回転は、Tic-Tac-Toe サーバー コンポーネントがアクティブ化されていて、MTS が正しくインストールされていることを示しています。ゲームを停止すると、Tic-Tac-Toe クライアントが Tic-Tac-Toe サーバー コンポーネントを使用しなくなるので、アイコンの回転が止まります。

[表示] メニューの [状態] をクリックすると、Tic-Tac-Toe コンポーネントの使用状況を確認できます。


管理オブジェクト サンプル スクリプトのセットアップ

管理オブジェクト サンプル スクリプトでは、Visual Basic Scripting Edition (VBScript) などのオートメーション互換の言語を使って MTS エクスプローラの処理を自動化するスクリプトを記述する方法を示します。サンプル スクリプトは Sample Bank アプリケーションの配置を自動化します。

サンプル スクリプトを実行するには、まず、Windows Scripting Host (WSH) をインストールしなければなりません。これらのスクリプトは、Microsoft Windows NT プラットフォームおよび Alpha プラットフォーム上でだけ動作することに注意してください。

Windows NT 4.0 Option Pack を使って Windows Scripting Host をインストールするには

1	WSH がインストールされていない場合は、[スタート] ボタンをクリックし、[プログラム] をポイントします。次に、[Microsoft インターネット サーバー (共通)] をポイントし、[Internet Information Server セットアップ] をクリックします。

2	セットアップ プログラムの [追加/削除] をクリックします。

3	コンポーネントの一覧の中から [Windows Scripting Host] を探し、チェック ボックスをオンにします。

4	[完了] をクリックします。Windows NT 4.0 Option Pack セットアップ プログラムによってコンピュータに WSH がインストールされます。

WSH がインストールされると、管理オブジェクト サンプル スクリプトを使用できるようになります。次のサンプル スクリプトが \Program Files\Mts\Samples\wsh ディレクトリにあります。

•	InstDLL.vbs

このスクリプトは、Sample Bank の既存のバージョンを削除し、Sample Bank という名前の新しいパッケージを作成します。次に、Sample Bank の Visual Basic DLL、Visual C++ DLL、および Visual J++ DLL からコンポーネントを新しいパッケージにインストールし、トランザクション属性を変更します。次に、新しいロールを追加します。スクリプトを実行する前に、ファイルのパスを変更しなければなりません。

このスクリプトでは、コンピュータのレジストリにすべてのコンポーネントのプログラム ID (prgID) が含まれている必要があることに注意してください。したがって、このスクリプトを実行する前に、Visual Studio� 97 ActiveX� ウィザードを使って Java コンポーネントを登録しなければなりません。

•	InstPak.vbs

このスクリプトは、Sample Bank パッケージを MTS ランタイム環境にインストールします。スクリプトを実行する前に、ファイルのパスを変更しなければなりません。

•	Uninst.vbs

このスクリプトは、Sample Bank パッケージを MTS ランタイム環境から削除します。スクリプトを実行する前に、ファイルのパスを変更しなければなりません。

•	InstDllCLI.vbs

このスクリプトを使うと、InstDll.vbs スクリプトをコマンド プロンプトから実行し、ファイル パスをパラメータとして入力することができます。InstDll.vbs スクリプトは Sample Bank の既存のバージョンを削除し、Sample Bank という名前の新しいパッケージを作成します。次に、Sample Bank の Visual Basic DLL、Visual C++ DLL、および Visual J++ DLL からコンポーネントを新しいパッケージにインストールし、トランザクション属性を変更します。次に、新しいロールを追加します。

•	InstPakCLI.vbs

このスクリプトを使うと、InstPak.vbs スクリプトをコマンド プロンプトから実行し、ファイル パスをパラメータとして入力することができます。InstPak.vbs スクリプトは Sample Bank パッケージを MTS ランタイム環境にインストールします。

管理スクリプト オブジェクトとサンプル スクリプトの詳細については、『管理者ガイド』の「MTS 管理の自動化」を参照してください。

管理オブジェクト サンプル スクリプトの制約

•	InstDLL.vbs スクリプトを実行する前に、Visual Studio 97 ActiveX ウィザードを使って Java コンポーネントを登録しなければなりません。

•	サンプル スクリプトを使った Java コンポーネントのインストールは、Alpha コンピュータまたは i386 コンピュータ上でだけサポートされます。Alpha コンピュータのユーザーは、スクリプトを実行する前に、InstDLL.vbs から Java コンポーネントのインポート用のコードを削除してください。


MTS に関する情報の入手

MTS に関する情報は、次の方法で入手できます。

•	ドキュメントを調べる。

•	Microsoft Transaction Server のホーム ページ http://www.microsoft.com/japan/products/ntserver/ にアクセスする。

•	製品サポート サービスに問い合わせる。

ドキュメントを調べる

MTS のドキュメントには、MTS の機能に関する概念説明、操作手順、リファレンス情報が記載されています。また、MTS エクスプローラやプログラミング言語のキーワードを使用しているときに、F1 キーを押すと、状況依存のヘルプを表示することができます。"状況依存" とは、[ヘルプ] メニューを使わずに、F1 キーを押すだけで直接ヘルプを表示できる機能のことです。

関連項目   ドキュメントの構成


MTS 管理者ガイド

『管理者ガイド』では、Microsoftｮ Transaction Server エクスプローラをいつどのように使用し、パッケージの作成、インストール、配布、および保守を行うかを説明します。このガイドには、次のユーザーを対象とする情報が記述されています。

•	システム管理者

•	Web 管理者

•	アプリケーション開発者

開発者は、MTS アプリケーションの作成、配置、および配布を行うための操作手順を参照できます。システム管理者と Web 管理者は、MTS エクスプローラを使って MTS アプリケーションの配置、管理、および保守を行うための操作手順を参照できます。

次のトピックでは、MTS エクスプローラを使ったパッケージの配置や管理について説明し、より詳細な手順が記述されたトピックへのリンクを提供しています。

MTS パッケージの作成について

MTS パッケージの配布について

MTS パッケージのインストールについて

MTS パッケージの保守について

MTS トランザクションの管理について

MTS の管理の自動化について

Windows 95/98 上の MTS エクスプローラ

Windowsｮ 95/98 オペレーティング システム上で MTS エクスプローラを使って MTS パッケージを管理することができます。ただし、Windows 95/98 上での MTS の管理には、次の制約があります。

•	Windows 95/98 コンピュータでリモート レジストリ サービスを実行している場合は、Windows 95/98 コンピュータを使ってリモートから Windows NT コンピュータを管理することができます。リモート レジストリ サービスを使用すると、(適切なアクセス権があれば) リモートの Windows 95/98 コンピュータのレジストリ エントリを変更できます。

リモート レジストリ サービスは、Windows 95/98 の CD-ROM の \Admin\Nettols\Remotreg ディレクトリにあります。Regserv.txt ファイルのリモート レジストリ サービスのインストール手順を参照し、リモート レジストリ セットアップ プログラム (Regserv.exe) を実行します。

•	Windows 95/98 上で実行している MTS を、リモートの別の Windows 95/98 コンピュータまたは Windows NT コンピュータから管理することはできません。

•	MTS エクスプローラのウィンドウの左側にツリー構造は表示されません。階層を下に移動するには、アイコンをダブルクリックし、上に移動するには、ツール バーの [1 つ上のレベル] ボタンをクリックします。

•	Windows 95/98 ではアプリケーション実行可能ファイル ユーティリティがサポートされていないため、MTS エクスプローラを使って実行可能ファイルを生成することはできません。アプリケーション実行可能ファイル ユーティリティの詳細については、「MTS 実行可能ファイルを生成する」を参照してください。

•	Windows 95/98 上の管理では、MTS セキュリティ プロパティまたは MTS ロールがサポートされていません。したがって、MTS エクスプローラで [ロール] フォルダ、[ロール メンバーシップ] フォルダ、および [ユーザー] フォルダを表示することはできません。

•	Windows 95/98 コンピュータでユーザーをロールに割り当てるには、Windows 95/98 コンピュータにユーザー レベルのアクセス管理を設定する必要があります。Windows 95/98 コントロール パネルを開いて [ネットワーク] をクリックします。[アクセス権の管理] タブをクリックして [ユーザー レベルのアクセス管理] を選択します。この設定の詳細については、Windows 95/98 のリソース キット を参照してください。

•	リモートの別のコンピュータ上のクライアントから Windows 95/98 上で実行しているコンポーネントにアクセスすることはできません。

•	Windows 95/98 にはシステム イベント ログがないので、イベント ログのエントリは、Windows ディレクトリの \MTSLogs サブディレクトリにある Transaction Server.html という名前の HTML ファイルに書き込まれます。この HTML ファイルを使って、システムまたはプログラムで発生した重大なイベントを監視することができます。

•	MTS サーバー プロセスが (フェイルファースト、アサート、またはアクセス違反によって) 予期せず終了した場合、そのアプリケーションを再開しようとすると、複数の MTS プロセスが生成されるという既知の問題があります。正しくは、パッケージごとに MTS プロセスが 1 つだけ動作する必要があります。サーバー プロセスが予期せず終了した場合、Windows 95/98 コンピュータを再起動する必要があります。

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド』


MTS パッケージの作成について

パッケージの作成は、開発過程の最終段階で行われます。パッケージ開発者、上級システム管理者、および上級 Web 管理者は、MTS エクスプローラを使ってパッケージの作成と配置を行います。アプリケーションの開発時に決定されるパッケージとコンポーネントの構成を MTS エクスプローラを使って実現します。

MTS アプリケーションを設計し、作成する方法の詳細については、『Programmer's Guide』の「Building MTS Applications (アプリケーションの作成)」を参照してください。

操作手順

空の MTS パッケージを作成する

MTS パッケージにコンポーネントを追加する

MTS コンポーネントをパッケージにインポートする

MTS パッケージからコンポーネントを削除する

エクスポート用の MTS パッケージを作成する

MTS パッケージのプロパティを設定する

MTS アクティブ化のプロパティを設定する

MTS トランザクションのプロパティを設定する

MTS 認証レベルを設定する

MTS パッケージをロックする

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド 』、MTS パッケージの配布について、MTS パッケージのインストールについて、MTS パッケージの保守について、MTS トランザクションの管理について、MTS の管理の自動化について


MTS パッケージの配布について

MTS アプリケーションのコンポーネントを作成し、パッケージに組み込んだら、アプリケーションをクライアントに配布します。アプリケーションを配布するには次の方法があります。

•	MTS エクスプローラを使って、使用しているサーバー コンピュータからシステム管理者または Web サイト管理者のサーバー コンピュータへコンポーネントをプッシュする方法。この場合は、両方のサーバー コンピュータで MTS を実行している必要があります。

•	MTS エクスプローラでアプリケーション実行可能ファイル ユーティリティを使って、リモート サーバーを参照するアプリケーション実行可能ファイルを自動的に生成する方法。クライアント アプリケーションで MTS を実行している必要はありません。

クライアントのコンピュータには、MTS がインストールされていることも、インストールされていないこともあるので、クライアントにサーバー パッケージを配布するときは、MTS エクスプローラのアプリケーション実行可能ファイル ユーティリティを使うことをお勧めします。アプリケーション実行可能ファイルは、リモートの MTS サーバーで実行しているコンポーネントにアクセスするようにクライアント コンピュータを自動的に構成します。MTS エクスプローラを使ってリモート コンポーネントを手動で構成することもできます。

プログラミングの知識がなくてもアプリケーション実行可能ファイル ユーティリティは使用できますが、MTS アプリケーションを配布するには、クライアント アプリケーションとサーバー アプリケーションをパッケージ化し、提供することの意味について熟知していなければなりません。たとえば、アプリケーションを正しくパッケージ化できないと、クライアント実行可能ファイルにサーバー アプリケーションのコードを挿入してクライアントに供給してしまうこともあります。

操作手順

リモート MTS コンピュータを使う

MTS パッケージのエクスポート

MTS 実行可能ファイルを生成する

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド 』、MTS パッケージの作成について、MTS パッケージのインストールについて、MTS パッケージの保守について、MTS トランザクションの管理について、MTS の管理の自動化について


MTS パッケージのインストールについて

パッケージを作成した後は、パッケージのインストールと配置を行いますが、それにはパッケージとコンポーネントのプロパティに関する知識が必要です。たとえば、パッケージをインストールしたら、システム管理者または Web 管理者は、パッケージに関連付けられているロールに Windows NT ユーザーをマップしなければなりません。システム管理者または Web 管理者は、アプリケーションを使用するユーザーとグループをロールにマップする前に、ロールに基づく宣言によるセキュリティとアプリケーションに関連付けられているロールについて、十分に理解してください。

操作手順

既成の MTS パッケージのインストール

MTS パッケージのアップグレード

MTS パッケージ セキュリティを有効にする

MTS パッケージ ID の設定

新しい MTS ロールの追加

MTS ロールをユーザーとグループにマップする

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド 』、MTS パッケージの作成について、MTS パッケージの配布について、MTS パッケージの保守について、MTS トランザクションの管理について、MTS の管理の自動化について


MTS パッケージの保守について

MTS エクスプローラを使って、インストールされているパッケージの状態を監視し、必要に応じてコンポーネントとパッケージのプロパティを再構成することによって、MTS アプリケーションを保守することができます。ここでは、既にインストールされ、配置されているパッケージを再構成する方法について説明します。

操作手順

MTS エクスプローラを使って状態とプロパティを監視する

MTS エクスプローラの [プロパティ] ダイアログ ボックスを使う

MTS ロールのユーザーを管理する

MTS のレプリケーションを使う

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド 』、MTS パッケージの作成について、MTS パッケージの配布について、MTS パッケージのインストールについて、MTS トランザクションの管理について、MTS の管理の自動化について


MTS トランザクションの管理について

MTS エクスプローラを使ってどのような状況でトランザクションを管理するかを理解するために、管理者は、分散トランザクションがどのように動作するかを理解してください。ここでは、トランザクション、トランザクションの状態、および管理の対象になっているトランザクションを監視し、管理する方法について説明します。

操作手順

MTS トランザクションについて

MS DTC の管理

MTS トランザクションの監視

Windows 95/98 で MTS トランザクションの監視

MTS トランザクションの状態について

MTS トランザクションの解決

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド 』、MTS パッケージの作成について、MTS パッケージの配布について、MTS パッケージのインストールについて、MTS パッケージの保守について、MTS の管理の自動化について


MTS の管理の自動化について

管理スクリプトを利用することによって、MTS エクスプローラによるパッケージとコンポーネントの構成を自動化することができます。Microsoft Visual Basic などのスクリプト言語の知識があれば、スクリプト オブジェクトを使って MTS エクスプローラの管理作業を自動化できます。たとえば、ツール開発者は、スクリプト オブジェクトを使って、リモート クライアントを自動的に構成するオブジェクトなどの MTS エクスプローラのアドインを作成することもできます。

注   スクリプト オブジェクトを使用するには、オートメーション互換のスクリプト言語の使い方に関する知識が必要です。

管理オブジェクト サンプル スクリプトと、Microsoft Visual Basic および Microsoft Visual C++ｮ API に関するリファレンス情報とスクリプト オブジェクトのサンプル コードが記載されている MTS 管理リファレンスを参照するには、"MTS 開発者用サンプルとドキュメント" をインストールしなければなりません。管理オブジェクト サンプル スクリプトは Visual Basic Script で記述されており、Windowsｮ NT 4.0 Option Pack セットアップ プログラムでインストールされる Windowsｮ Scripting Host を使用します。MTS 管理スクリプトの使い方の詳細については、「管理オブジェクト サンプル スクリプトのセットアップ」を参照してください。

操作手順

MTS 管理オブジェクト

MTS 管理自動化 Visual Basic Script サンプル

MTS 管理自動化 Visual Basic サンプル アプリケーション

Visual Basic による MTS 管理の自動化

Visual Basic による高度な MTS 管理の自動化

関連項目

『Microsoft Transaction Server のクイック ツアー』、『Microsoft Transaction Server ファースト ステップ ガイド 』、Microsoft Transaction Server ファースト ステップ ガイド、MTS パッケージの作成について、MTS パッケージの配布について、MTS パッケージのインストールについて、MTS パッケージの保守について、MTS トランザクションの管理について


MTS エクスプローラの階層

MTS エクスプローラは、MTS ランタイム環境で実行している MTS パッケージと MTS コンポーネントを管理するためのビジュアル ツールです。MTS エクスプローラを使って、コンポーネントのパッケージへの組み込みからトランザクションの状態の監視までの作業を実行します。

MTS エクスプローラは、Windows NT 上では Microsoft Management Console (MMC) をホストとするスナップインであり、Windows 95/98 上では実行可能ファイル (mtxpd.exe) です。MTS エクスプローラのウィンドウの左側の階層ツリーには、次の項目が含まれています。

•	[コンピュータ]

このサーバーから管理するコンピュータが含まれています。ローカル コンピュータには "マイ コンピュータ" という名前が付いています。

•	[インストールされたパッケージ]

コンピュータにインストールされたパッケージが含まれています。

•	[リモート コンポーネント]

ローカル コンピュータ上のパッケージが使用するリモート コンピュータ上のコンポーネントが含まれています。

•	[トランザクションの一覧]

MTS アプリケーションが参加している現在のトランザクションが表示されます。

•	[トランザクションの統計]

ローカル コンピュータが参加しているトランザクションの統計情報が表示されます。

•	[トレース メッセージ]

Microsoft 分散トランザクション コーディネータ (MS DTC) が発行している現在のトレース メッセージの一覧が表示されます。

注   Windows 95/98 上の MTS エクスプローラには、ウィンドウ領域が 1 つしかありません。Windows 95/98 上で MTS エクスプローラの階層を下に移動するには、アイコンをダブルクリックし、階層を上に移動するには、ツール バーの [1 つ上のレベル] ボタンをクリックします。

また、Windows 95/98 上では、[リモート コンポーネント] フォルダおよびアプリケーション実行可能ファイル ユーティリティは使用できません。

Windows 95/98 上の MTS エクスプローラの制約については、『管理者ガイド』の「Windows 95/98 上の MTS エクスプローラ」を参照してください。

MTS エクスプローラが管理するリモート コンピュータでは、コンピュータのアイコンの下の階層に [インストールされたパッケージ] フォルダ、[リモート コンポーネント] フォルダ、[トランザクションの一覧]、[トランザクションの統計]、および [トレース メッセージ] の各ウィンドウの一覧が表示されます。

MTS エクスプローラのインストールされた個々のパッケージには、次のサブフォルダが含まれています。

•	[コンポーネント] フォルダ

パッケージに組み込まれているコンポーネントが含まれています。

•	[ロール] フォルダ

パッケージ内で使用できるロールが含まれています。

•	[ロール メンバーシップ] フォルダ

コンポーネントまたはコンポーネントのインターフェイスに割り当てられているロールが含まれています。

•	[ユーザー] フォルダ

パッケージのロールにマップされているユーザーが含まれています。

•	[インターフェイス] フォルダ

コンポーネントのインターフェイスが含まれています。

•	[メソッド] フォルダ

インターフェイスのメソッドが含まれています。

関連項目

『Microsoft Transaction Server のクイック ツアー』


[コンピュータ] フォルダ

[コンピュータ] フォルダには、[マイ コンピュータ] と、ユーザーが [コンピュータ] フォルダに追加したそのほかのコンピュータが含まれています。既定の設定では、MTS がインストールされているローカル コンピュータが [マイ コンピュータ] に相当します。

[コンピュータ] フォルダにコンピュータを追加するには、次のいずれかの操作を実行します。

•	[コンピュータ] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[コンピュータ] をクリックします。

•	[コンピュータ] フォルダを選択し、ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

•	[コンピュータ] フォルダを選択し、[動作] メニューの [新規作成] をポイントします。次に、[コンピュータ] をクリックします。

[コンピュータの追加] ダイアログ ボックスで、使用しているコンピュータから管理するサーバーの名前を入力します。新しいサーバーが [コンピュータ] フォルダに追加され、MTS エクスプローラの階層の [マイ コンピュータ] アイコンと同じレベルに表示されます。

関連項目

[マイ コンピュータ]、コンピュータのプロパティ


[マイ コンピュータ]

[マイ コンピュータ] は、MTS がインストールされているローカル コンピュータです。

[コンピュータ] フォルダのレベルで実行できる操作については、次のトピックを参照してください。

MTS のレプリケーションを使う

MS DTC の管理

すべての [コンピュータ] フォルダに次の項目が含まれています。

[インストールされたパッケージ]

このコンピュータが管理しているシステム パッケージと、ユーザーがインストールしたパッケージが含まれています。

[リモート コンポーネント]

ローカル コンピュータ上のパッケージが呼び出すリモート コンピュータ上のコンポーネントが含まれています。

[トランザクションの一覧]

このコンピュータが管理している現在のトランザクションの一覧が表示されます。

[トランザクションの統計]

コンピュータが参加しているトランザクションの統計情報が表示されます。

[トレース メッセージ]

Microsoft 分散トランザクション コーディネータ (MS DTC)が発行している現在のトレース メッセージの一覧が表示されます。

[コンピュータ] フォルダ内のすべてのコンピュータと同様に、[マイ コンピュータ] のプロパティも次のタブを使って構成することができます。

•	[全般] タブ

•	[オプション] タブ

•	[詳細設定] タブ

関連項目

[コンピュータ] フォルダ


[インストールされたパッケージ] フォルダ

[インストールされたパッケージ] フォルダには、ユーザーがコンピュータに追加したすべてのパッケージの一覧が表示されます。パッケージ レベルでは、次の操作を実行できます。

空の MTS パッケージを作成する

既成の MTS パッケージのインストール

MTS パッケージのアップグレード

MTS パッケージのプロパティを設定する

MTS アクティブ化のプロパティを設定する

MTS パッケージ ID の設定

MTS パッケージ セキュリティを有効にする

MTS トランザクションのプロパティを設定する

MTS パッケージをロックする

MTS パッケージのエクスポート

MTS エクスプローラを使って状態とプロパティを監視する

MTS エクスプローラの [プロパティ] ダイアログ ボックスを使う

[インストールされたパッケージ] フォルダには、次のシステム パッケージも含まれています。

System パッケージ

Utilities パッケージ

注   これらのパッケージは MTS の内部パッケージであり、通常は変更したり構成したりしないでください。ただし、MTS サーバーの権限を拡張したり制限したりするには、MTS の内部パッケージを構成する必要がある場合があります。たとえば、MTS サーバー上のユーザーの管理権限を設定するには、System パッケージの Administrator ロールにユーザーを追加します。

[インストールされたパッケージ] フォルダには、いくつでもパッケージをインストールすることができます。インストールされた個々のパッケージには、次のサブフォルダが含まれています。

•	[コンポーネント] フォルダ

パッケージに組み込まれているコンポーネントが含まれています。

•	[ロール] フォルダ

パッケージに割り当てられているロールが含まれています。

次のタブを使ってパッケージのプロパティを構成することができます。

•	[全般] タブ

•	[セキュリティ] タブ

•	[詳細設定] タブ

•	[ID] タブ

•	[アクティブ化] タブ

MTS を Internet Information Server (IIS) Version 4.0 と組み合わせて使用している場合は、[インストールされたパッケージ] フォルダに次の IIS 固有のシステム パッケージも含まれています。

•	IIS インプロセス アプリケーション

[IIS In-Process Applications] フォルダには、Internet Information Server (IIS) のプロセスで実行されている各 IIS アプリケーションのコンポーネントが含まれています。IIS アプリケーションは、IIS のプロセスまたは別のアプリケーションのプロセスで実行できます。IIS アプリケーションが IIS のプロセスで実行されている場合、IIS アプリケーションは [IIS In-Process Applications] フォルダ内にコンポーネントとして表示されます。IIS アプリケーションが別のアプリケーションのプロセスで実行されている場合、IIS アプリケーションは MTS エクスプローラの階層に独立したパッケージとして表示されます。

•	IIS ユーティリティ

[IIS Utilities] フォルダには、Active Server Pages (ASP) でトランザクションを有効にするために必要な ObjectContext コンポーネントが含まれています。トランザクション ASP の詳細については、Internet Information Server (IIS) のドキュメントを参照してください。

Microsoft Transaction Server は、内部関数で ObjectContext コンポーネントを使用します。このコンポーネントのプロパティを表示することはできますが、設定することはできません。

注  プロセスを分離して保護された IIS アプリケーションを作成する場合、IIS は IWAN_<computer name> として実行されるように MTS パッケージを作成します。これらのパッケージの ID を変更する場合、新しいパッケージ ID を "MTS Impersonators" グループにも追加する必要があります。さもなければ、パッケージが呼び出すプロセス外のほかのコンポーネントでは、セキュリティ機能が正しく機能しません。これを行わないと、呼び出し元は、IIS の実際のクライアントではなく、IWAN_<computer name> と見なされます。


Utilities パッケージ

Utilities パッケージには、TransactionContext と TransactionContextEx の 2 つのコンポーネントが含まれています。ベース クライアントで TransactionContext/TransactionContextEx を使用して 1 つまたは複数の Microsoft Transaction Server オブジェクトの動作を組み合わせたアトミック トランザクションを作成し、そのトランザクションをアボートしたり、コミットしたりすることができます。

関連項目

MTS トランザクションの管理


System パッケージ

System パッケージには、変更できないコンポーネントが含まれています。Microsoft Transaction Server は、これらのコンポーネントを内部関数で使用します。システム コンポーネントのプロパティを表示することはできますが、設定することはできません。

MTS エクスプローラによって管理されているパッケージをユーザーが削除したり変更したりするには、そのユーザーは System パッケージの Administrator ロールにマップされていなければなりません。プライマリ ドメイン コントローラまたはバックアップ ドメイン コントローラの役割を果たしているサーバーに MTS がインストールされている場合、ユーザーが MTS エクスプローラでパッケージを管理するには、そのユーザーはドメイン管理者になっていなければなりません。

関連項目

MTS サーバーの構成、MTS パッケージ セキュリティを有効にする、MTS ロールをユーザーとグループにマップする、[ユーザー] フォルダ


[コンポーネント] フォルダ

[コンポーネント] フォルダには、選択されているパッケージ内のコンポーネントが含まれています。

コンポーネント レベルでの操作手順については、次のトピックを参照してください。

MTS パッケージにコンポーネントを追加する

MTS コンポーネントをパッケージにインポートする

MTS パッケージからコンポーネントを削除する

MTS エクスプローラを使って状態とプロパティを監視する

MTS エクスプローラの [プロパティ] ダイアログ ボックスを使う

MTS トランザクションのプロパティを設定する

MTS 認証レベルを設定する

[コンポーネント] フォルダには、次のサブフォルダが含まれています。

•	[インターフェイス] フォルダ

コンポーネントに関連付けられているインターフェイスが含まれています。

•	[ロール メンバーシップ] フォルダ (コンポーネント)

コンポーネントのロールに関連付けられているロールとユーザーが含まれています。

次のタブを使ってコンポーネントのプロパティを構成することができます。

•	[全般] タブ

•	[トランザクション] タブ

•	[セキュリティ] タブ

関連項目

MTS アクティブ化のプロパティを設定する


[ロール] フォルダ

[ロール] フォルダには、選択されているパッケージに割り当てられているロールが含まれています。MTS では、パッケージ、コンポーネント、またはインターフェイスへのユーザーのアクセスを制御するロールを定義することができます。パッケージの [ロール] フォルダに追加するロールは、いずれもそのパッケージ内のコンポーネントまたはインターフェイスの [ロール メンバーシップ] フォルダにも追加することができます。

ロール レベルでは、次の操作を実行することができます。

MTS ロールをユーザーとグループにマップする

MTS パッケージ セキュリティを有効にする

新しい MTS ロールの追加

[ロール] フォルダには、次のサブフォルダが含まれています。

•	[ユーザー] フォルダ

次のタブを使ってロールのプロパティを構成することができます。

•	[全般] タブ

関連項目

MTS サーバーの構成、System パッケージ


[インターフェイス] フォルダ

[インターフェイス] フォルダには、選択されているコンポーネントに定義されているインターフェイスが含まれています。

[インターフェイス] フォルダには、次の 2 つのサブフォルダが含まれています。

•	[メソッド] フォルダ

•	[ロール メンバーシップ] フォルダ

次のタブを使ってインターフェイスのプロパティを表示することができます。

•	[全般] タブ

•	[プロキシ] タブ

[全般] タブにインターフェイスの説明を追加する場合以外は、インターフェイスのプロパティを構成することはできません。

関連項目

MTS パッケージ セキュリティを有効にする


[メソッド] フォルダ

[メソッド] フォルダには、選択されているインターフェイスで定義されているメソッドが含まれています。

メソッドのプロパティには、次のタブがあります。

•	[全般] タブ

[全般] タブにメソッドの説明を追加する場合以外は、メソッドを構成することはできません。

関連項目

[インターフェイス] フォルダ


[ロール メンバーシップ] フォルダ

[ロール メンバーシップ] フォルダには、ユーザーがコンポーネントまたはインターフェイスに関連付けたロールが含まれています。これらのロールをパッケージの [ロール] フォルダから [ロール メンバーシップ] フォルダに追加すると、インターフェイスまたはコンポーネントにアクセスできるユーザーを制御することができます。

ロール メンバーシップのプロパティは、[ロール] フォルダ レベルで設定します。たとえば、パッケージのロールの説明を入力すると、その説明は、ロール メンバーシップ レベルでロールの説明として表示されます。

宣言によるセキュリティの詳細については、「MTS パッケージ セキュリティを有効にする」を参照してください。

関連項目

[インターフェイス] フォルダ


[ユーザー] フォルダ

[ユーザー] フォルダには、管理者がロールに関連付ける Windows NT ユーザーまたはグループが含まれています。各ユーザーは、管理者がパッケージの [ロール] フォルダに追加する Windows NT ユーザー アカウントを表します。[ロール] フォルダに Windows NT ユーザー アカウントまたはグループを追加すると、パッケージ、コンポーネント、およびインターフェイスへのアクセスを制御することができます。

ユーザー レベルでは、次の操作を実行することができます。

•	ロールに新しいユーザーやグループを追加する。

•	ロールからユーザーやグループを削除する。

[ユーザー] フォルダに関連する [プロパティ] ダイアログ ボックスはありません。

関連項目

MTS パッケージ セキュリティを有効にする、MTS ロールをユーザーとグループにマップする


[リモート コンポーネント] フォルダ

[リモート コンポーネント] フォルダには、別のコンピュータ上でリモートから実行するために、このコンピュータにローカルで登録されているコンポーネントが含まれています。[リモート コンポーネント] フォルダを使用するには、構成するクライアント コンピュータに MTS がインストールされている必要があります。MTS エクスプローラを使ってリモート コンピュータを手動で構成する場合は、リモート コンピュータがアクセスするコンポーネントを [リモート コンポーネント] フォルダに追加します。

リモート コンポーネントを構成する前に、リモート コンポーネントを実行するすべてのサーバーを自分の [コンピュータ] フォルダに追加してください。

MTS を実行しているリモート コンピュータの使い方の詳細については、次のトピックを参照してください。

MTS パッケージのエクスポート

リモート MTS コンピュータを使う

注   Windows 95/98 上で実行しているコンポーネントに別のコンピュータ上のクライアントからリモートでアクセスすることはできません。詳細については、『管理者ガイド』の「Windows 95/98 上の MTS エクスプローラ」を参照してください。

関連項目

MTS 実行可能ファイルを生成する


[トランザクションの一覧] ウィンドウ

[トランザクションの一覧] ウィンドウには、次のトランザクションを含む、このコンピュータが参加している現在のトランザクションが表示されます。

•	イン ダウトの状態のトランザクション。

•	コンピュータの [プロパティ] ダイアログ ボックスの [詳細設定] タブで指定した時間に該当するトランザクション。

[トランザクションの一覧] ウィンドウに表示されるアイコンの説明については、「トランザクション アイコン」を参照してください。

トランザクションの管理の概要については、次のトピックを参照してください。

•	MTS トランザクションについて

•	MTS トランザクションの状態について

[トランザクションの一覧] ウィンドウを使って、次の作業を行うことができます。

•	MTS トランザクションの監視

•	Windows 95/98 で MTS トランザクションの監視

•	MTS トランザクションの解決

トランザクションをマウスの右ボタンでクリックし、[プロパティ] をクリックしてトランザクションのプロパティを表示することもできます。

関連項目

トランザクション アイコン、MS DTC の管理


[トランザクションの統計] ウィンドウ

[トランザクションの統計] ウィンドウには、コンピュータが参加しているトランザクションの統計情報が表示されます。統計情報には、累積値を示すものと、現在のパフォーマンスを反映するものがあります。

トランザクションの管理の概要については、次のトピックを参照してください。

•	MTS トランザクションについて

•	MTS トランザクションの状態について

[トランザクションの統計] ウィンドウを使って、次の作業を行うことができます。

•	MTS トランザクションの監視

•	Windows 95/98 で MTS トランザクションの監視

•	MTS トランザクションの解決

Windows NT 上で MTS エクスプローラを使用している場合は、1 つのサーバーについて 1 つだけ [トランザクションの統計] ウィンドウを開くことができることに注意してください。

[カレント]

•	[アクティブ] ─ 2 フェーズ コミット プロトコルを完了していないトランザクションの現在の数を示します。

•	[最大アクティブ] ─ 現在の Microsoft 分散トランザクション コーディネータ (MS DTC) セッション中の任意の時点でのアクティブ トランザクションの最大数を示します。

•	[イン ダウト] ─ ローカル データベース サーバーとコミット コーディネータとの間で通信障害が発生したためにコミットできないトランザクションの現在の数を示します。

[集計]

•	[コミット] ─ コミットされたトランザクションの累積合計数を示します。ただし、強制 (手動で解決された) コミットは含まれません。

•	[アボート] ─ アボートされたトランザクションの累積合計数を示します。ただし、強制アボートは含まれません。

•	[強制コミット] ─ 手動でコミットされたトランザクションの累積合計数を示します。

•	[強制アボート] ─ 手動でアボートされたトランザクションの累積合計数を示します。

•	[合計] ─ すべてのトランザクションの累積合計数を示します。

[応答時間 (ミリ秒)]

このグループには、トランザクションの最小、平均、および最大の応答時間がミリ秒単位で表示されます。応答時間とは、トランザクションの開始からコミットまでの所要時間です。

[MS DTC 開始/MS DTC 停止]

このグループには、現在の MS DTC セッションが開始された日付と時刻が表示されます。MS DTC が開始されないと日付と時刻は表示されません。

統計情報には、累積値を示すものと、現在のパフォーマンスを反映するものがあります。

MS DTC サービスを停止すると、累積統計情報の値はすべて 0 にリセットされます。

関連項目

MS DTC の管理


[トレース メッセージ] ウィンドウ

[トレース メッセージ] ウィンドウには、Microsoft 分散トランザクション コーディネータ (MS DTC) が発行している現在のトレース メッセージの一覧が表示されます。トレースを行うと、スタートアップやシャットダウンなど、MS DTC のさまざまなアクティビティの現在の状態を表示したり、デバッグ情報に基づいて潜在的な問題を追跡することができます。

トランザクションの管理の概要については、次のトピックを参照してください。

•	MTS トランザクションについて

•	MTS トランザクションの状態について

[トレース メッセージ] ウィンドウを使って、次の作業を行うことができます。

•	MTS トランザクションの監視

•	Windows 95/98 で MTS トランザクションの監視

コンピュータの [プロパティ] ダイアログ ボックスの [詳細設定] タブで、[トレース] のつまみを使って、このウィンドウに表示されるトレースのレベルを指定することができます。

[重大さ]

アイコン	説明
	エラー MS DTC の再起動が必要な問題が発生しました。たとえば、ログ ファイルの破損が検出された場合です。
	警告 まもなく異常が発生する可能性があります。
	情報 スタートアップやシャットダウンなど、頻度の低いイベントに関する情報が表示されます。
	トレース 新しいクライアント接続、リソース マネージャの登録などのイベントに関するデバッグ情報が表示されます。
[ソース]

トレース メッセージの発行元が次のように表示されます。

•	[SVC] ─ MS DTC サービスがトレース メッセージの発行元です。

•	[LOG] ─ MS DTC ログがトレース メッセージの発行元です。

•	[CM] ─ MS DTC ネットワーク接続マネージャがトレース メッセージの発行元です。

トレース メッセージと Windows NT イベント ログのメッセージには、発行元のタグが付きます。

[メッセージ]

メッセージが表示されます。

関連項目

MS DTC の管理


トランザクション アイコン

[トランザクションの一覧] ウィンドウには次のアイコンが表示されます。

アイコン	説明
	アクティブ トランザクションが開始されました。
	アボート中 トランザクションをアボートしています。MS DTC は、すべての関連部分に、トランザクションをアボートしなければならないことを通知しています。 この時点でトランザクションの結果を変更することはできません。
	アボート トランザクションがアボートされました。すべての関連部分は、通知を受けました。アボートされたトランザクションは、[トランザクションの一覧] ウィンドウのトランザクションの一覧からすぐに削除されます。 この時点でトランザクションの結果を変更することはできません。
	準備中 クライアント アプリケーションがコミット要求を発行しました。MS DTC は、すべての関連部分から準備完了の応答を集めています。
	準備完了 すべての関連部分が準備完了の応答を返しました。
	イン ダウト トランザクションが別の MS DTC によって準備され、調整されており、その調整役の MS DTC がアクセスできなくなっています。システム管理者は、[トランザクションの一覧] ウィンドウ内でマウスの右ボタンをクリックし、[解決] をポイントします。次に、[コミット] または [アボート] をクリックすると、強制的にトランザクションをコミットまたはアボートさせることができます。強制的に処理を行うと、そのトランザクションは [強制コミット] または [強制アボート] として表示されます。 警告   イン ダウトのトランザクションを手動で強制的に処理する前に、必ず「MTS トランザクションの解決」をお読みください。
	強制コミット 管理者が、イン ダウトのトランザクションを強制的にコミットしました (「MTS トランザクションの解決」を参照してください)。
	強制アボート 管理者が、イン ダウトのトランザクションを強制的にアボートしました (「MTS トランザクションの解決」を参照してください)。
	コミット中 トランザクションが正しく準備され、MS DTC が関連部分に、トランザクションがコミットされたことを通知しています。MS DTC は、すべての関連部分がコミット要求の受信 (およびログの記録) を確認するまで、そのトランザクションを終了しません。 この時点でトランザクションの結果を変更することはできません。
	アボートを通知できません MS DTC は、すべての接続されている関連部分に、トランザクションがアボートされたことを通知しました。通知を受けていないのは、現在アクセスできない関連部分だけです。 このトランザクション状態は、MS DTC がいずれかのリソース マネージャ (IBM LU 6.2 システムなど) にトランザクションがアボートされたことを通知しなければならないのに、そのシステムとの接続が切断されているため、通知できないときに発生します。 システム管理者は、[トランザクションの一覧] ウィンドウ内でマウスの右ボタンをクリックし、[解決] をポイントします。次に、[破棄] をクリックすると、MS DTC にトランザクションを強制的に破棄させることができます。 警告   トランザクションを手動で破棄する前に、必ず「MTS トランザクションの解決」をお読みください。
	コミットを通知できません MS DTC は、すべての接続されている関連部分に、トランザクションがコミットされたことを通知しました。通知を受けていないのは、現在アクセスできない関連部分だけです。 システム管理者は、[トランザクションの一覧] ウィンドウ内でマウスの右ボタンをクリックし、[解決] をポイントします。次に、[破棄] をクリックすると、MS DTC にトランザクションを強制的に破棄させることができます。 警告   トランザクションを手動で破棄する前に、必ず「MTS トランザクションの解決」をお読みください。
	コミット トランザクションがコミットされ、すべての関連部分が通知を受けました。コミットされたトランザクションは、[トランザクションの一覧] ウィンドウのトランザクションの一覧からすぐに削除されます。 この時点でトランザクションの結果を変更することはできません。
関連項目

MS DTC の管理


コンピュータのプロパティ

コンピュータのプロパティでは、コンピュータに関する全般的な情報を設定し、Microsoft Transaction Server がコンピュータを更新する方法を制御します。

[全般] タブ

[オプション] タブ

[詳細設定] タブ

関連項目

[コンピュータ] フォルダ


[全般] タブ (コンピュータ)

[全般] タブでは、コンピュータの名前と説明を定義します。

名前

コンピュータの名前が表示されます。

[説明]

コンピュータの説明が表示されます。コンピュータの識別と管理に役立つ説明を入力することができます。

関連項目

[コンピュータ] フォルダ


[オプション] タブ (コンピュータ)

[オプション] タブは、コンピュータのトランザクション タイムアウト プロパティとレプリケーション情報を設定するときに使います。

トランザクション タイムアウト値は秒単位で計測され、このコンピュータで開始されたトランザクションがアクティブな状態を維持できる最大限の時間を示します。指定した時間を過ぎてもアクティブになっているトランザクションは、システムが自動的にアボートします。既定値は 60 秒です。トランザクション タイムアウトを無効にするには、値を 0 に設定します。無効にすると、MTS アプリケーションのデバッグ時に便利です。

[オプション] タブの [レプリケーション] を使って、使用している MTS コンピュータのレプリケーション情報を入力します。フェールオーバー サポートを有効にするには、[レプリケーションの共有ディレクトリ] ボックスに Microsoft Cluster Server (MSCS) の仮想サーバー名を入力します。Windows 95/98 コンピュータ上で MTS カタログをレプリケートすることはできません。

クライアント実行可能ファイルにアクセスさせるコンピュータを指定することもできます。アプリケーション実行可能ファイルを生成する前に、クライアントがアクセスする物理サーバーの名前を [リモート サーバー名] ボックスに入力します。このボックスに何も入力しないと、エクスポートを行ったコンピュータの物理コンピュータ名が使われます。文字列としてリモート サーバーの名前を入力すると、MTS エクスプローラが生成するアプリケーション実行可能ファイルは、そのリモート サーバー名を指します。

関連項目

MTS のレプリケーションを使う、MTS 実行可能ファイルを生成する、[コンピュータ] フォルダ


[詳細設定] タブ (コンピュータ)

[詳細設定] タブは、Microsoft 分散トランザクション コーディネータ (MS DTC) のプロパティを構成するときに使います。このタブの設定は、[トランザクションの一覧]ウィンドウ、[トランザクションの統計] ウィンドウ、および [トレース メッセージ] ウィンドウにだけ適用されます。

注   [マイ コンピュータのプロパティ] ダイアログ ボックスの [詳細設定] タブからヘルプを表示することはできません。

[表示]

•	[更新頻度] ─ [低] から [高] までの範囲をつまみで設定します。[低] ではトランザクション ウィンドウが 20 秒ごとに更新され、[高] では 1 秒ごとに更新されます。更新の頻度を上げると、実行中のトランザクションの管理オーバーヘッドは増加しますが、最新の情報を表示できます。

•	[トランザクション表示] ─ [旧] から [新 + 旧] までの範囲をつまみで設定します。[旧] に設定すると 5 分以上アクティブになっているトランザクションだけが表示され、[新 + 旧] に設定すると 1 秒以上アクティブになっているトランザクションが表示されます。

•	[トレース] ─ [少 (高速 MS DTC)] から [多 (低速 MS DTC)] までの範囲をつまみで設定します。左側の目盛りから順に、次の設定に対応します。

•	トレースを送信しない。

•	エラー トレースだけを送信する。

•	エラー トレースと警告トレースを送信する。

•	エラー トレース、警告トレース、および情報トレースを送信する (既定の設定)。

•	すべてのトレースを送信する。

[ログ]

•	[場所] ─ ログ ファイルを格納する場所を指定します。

•	[容量] ─ ログ ファイルの最大のサイズを指定します。

[ログのリセット]

何らかの変更が加えられた後でログ ファイルを更新するときに使います。

警告   未解決のトランザクションの実行中は、MS DTC のログ ファイルを更新しないでください。

トランザクションの管理の概要については、次のトピックを参照してください。

•	MTS トランザクションについて

•	MTS トランザクションの状態について

MTS エクスプローラで [トランザクションの統計] ウィンドウ、[トレース メッセージ] ウィンドウ、および [トランザクションの一覧] ウィンドウを使用する方法については、次のトピックを参照してください。

•	MTS トランザクションの監視

•	Windows 95/98 で MTS トランザクションの監視

関連項目

MS DTC の管理


パッケージのプロパティ

パッケージのプロパティでは、パッケージにアクセスする方法を制御します。

[全般] タブ

[セキュリティ] タブ

[詳細設定] タブ

[ID] タブ

[アクティブ化] タブ

重要   ライブラリ パッケージの [プロパティ] ダイアログ ボックスを使って、[セキュリティ] タブまたは [ID] タブのプロパティを変更する (またはパッケージをシャットダウンする) ことはできません。

ロールに基づくセキュリティは Windows NT だけでサポートされているため、Windows 95/98 コンピュータではパッケージの [プロパティ] ダイアログ ボックスに [セキュリティ] タブがありません。

関連項目

[インストールされたパッケージ] フォルダ


[全般] タブ (パッケージ)

[全般] タブには、選択されているパッケージに関する全般的な情報が表示されます。

名前

パッケージの名前が表示されます。

[説明]

パッケージの説明が表示されます。パッケージの識別と管理に役立つ説明を入力することができます。

[パッケージ ID]

パッケージ ID 番号が表示されます。パッケージ ID 番号は、パッケージの作成時に生成される一意の番号です。パッケージ ID を使ってコンピュータ上の特定のバージョンのパッケージを識別できます。

関連項目

[インストールされたパッケージ] フォルダ、パッケージのプロパティ


[セキュリティ] タブ (パッケージ)

[セキュリティ] タブには、選択されているパッケージに関するセキュリティ情報が表示されます。

[認証の確認を実行する]

このチェック ボックスをオンにすると、パッケージを呼び出すすべてのクライアントのセキュリティ情報がチェックされます。既定の設定では、認証の確認は実行されません。

[呼び出しの認証レベル]

パッケージを呼び出すクライアントの認証レベルを設定します。

関連項目

[インストールされたパッケージ] フォルダ、パッケージのプロパティ、MTS 認証レベルを設定する、MTS パッケージ セキュリティを有効にする


[詳細設定] タブ (パッケージ)

[詳細設定] タブでは、パッケージに関連付けられたサーバー プロセスを常に実行するか、または一定の時間が過ぎたらシャットダウンするかを設定します。

パッケージが非アクティブのまま一定の時間が過ぎたら自動的にシャットダウンさせる場合は、[一定時間アイドルした後でシャットダウンする] を選択し、サーバー プロセスがシャットダウンするまでの時間を設定します。

サーバー プロセスを常に利用可能な状態にする場合は、[アイドル状態のときも実行を続ける] を選択してください。

[動作] メニューの [サーバー プロセスのシャットダウン] コマンドを使って、選択されているコンピュータで実行しているすべてのサーバー プロセスをシャットダウンすることができます。

関連項目

[インストールされたパッケージ] フォルダ


[ID] タブ (パッケージ)

[ID] タブは、パッケージで実行しているすべてのコンポーネントのユーザー ID を設定するときに使います。既定値は [対話ユーザー - 現在ログオンしているユーザー] です。このユーザーは、Windows NT Server のアカウントにログオンしたユーザーです。別のユーザーを選択する場合は、[このユーザー] を選択し、アカウント名とパスワードを指定します。

重要   パッケージ ID を設定したとき、MTS は入力されたパスワードを確認します。ただし、アカウントのパスワードを変更したときに MTS エクスプローラでパスワードを更新しなかった場合は、パッケージは実行できません。別のユーザーとパスワードを指定する場合、パスワードの指定時にはパスワードの確認が行われます。ただし、アカウントのパスワードを変更した場合に MTS エクスプローラを使ってパスワードを更新しないと、パッケージを実行できません。無効なパスワードを使ってパッケージを実行すると、ランタイム エラーが発生し、メッセージがイベント ログに記録されます。

[このユーザー] を選択してユーザーを設定するには、そのユーザーにマップされているコンピュータにログオンしていなければなりません。

関連項目

MTS 認証レベルを設定する、[インストールされたパッケージ] フォルダ


[アクティブ化] タブ (パッケージ)

[アクティブ化] タブは、パッケージ内でコンポーネントをアクティブ化する方法を設定するときに使います。

パッケージは、パッケージを呼び出したクライアントのプロセス内で (ライブラリ パッケージとして) 実行するように設定するか、またはパッケージ専用のローカル プロセス内で (サーバー パッケージとして) 実行するように設定することができます。

[ライブラリ パッケージ]

パッケージをライブラリ パッケージとして実行するには、このオプションを選択します。ライブラリ パッケージは、パッケージの作成元クライアントのプロセス内で実行されます。このオプションは、パッケージがインストールされ、構成されているコンピュータ上のクライアントでだけ選択できます。ライブラリ パッケージは、コンポーネントの追跡、ロールのチェック、プロセスの分離を行いません。

[サーバー パッケージ]

パッケージをサーバー パッケージとして実行するには、このオプションを選択します。サーバー パッケージは、ローカル コンピュータ上のサーバー パッケージ自体のプロセス内で実行されます。サーバー パッケージは、ロールに基づくセキュリティ、リソースの共有、プロセスの分離、(パッケージの追跡などの) プロセス管理をサポートします。

関連項目

[インストールされたパッケージ] フォルダ、パッケージのプロパティ


コンポーネントのプロパティ

コンポーネントのプロパティでは、トランザクションのサポートとセキュリティの設定を制御します。[全般] タブを使って、名前、プログラム ID (ProgID)、およびクラス ID (CLSID) など、コンポーネントを識別するためのプロパティを表示することもできます。

[全般] タブ

[トランザクション] タブ

[セキュリティ] タブ

関連項目

[コンポーネント] フォルダ、MTS パッケージ セキュリティを有効にする


[全般] タブ (コンポーネント)

[全般] タブには、選択されているコンポーネントに関する全般的な情報が表示されます。

コンポーネントの Prog ID

プログラム ID (ProgID) が表示されます。

[説明]

コンポーネントの説明が表示されます。コンポーネントの識別と管理に役立つ説明を入力することができます。

[DLL]

コンポーネントのクラスとインターフェイスの定義を含む DLL のパスが表示されます。

[CLSID]

コンポーネントのクラス ID (CLSID) が表示されます。コードの中でクラス ID (CLSID) を使って、コンポーネントを識別したり、アクセスしたりすることができます。

[パッケージ]

コンポーネントがインストールされているパッケージの名前が表示されます。

関連項目

[コンポーネント] フォルダ、コンポーネントのプロパティ


[セキュリティ] タブ (コンポーネント)

[セキュリティ] タブは、選択されているコンポーネントのセキュリティを構成するときに使います。宣言によるセキュリティについては、「MTS パッケージ セキュリティを有効にする」を参照してください。

[認証の確認を実行する]

このチェック ボックスをオンにすると、コンポーネントを呼び出すすべてのクライアントのセキュリティ情報がチェックされます。

関連項目

[コンポーネント] フォルダ、コンポーネントのプロパティ


[トランザクション] タブ (コンポーネント)

[トランザクション] タブでは、コンポーネントがトランザクションをサポートする方法を指定します。

•	[トランザクションが必要] ─ コンポーネントのオブジェクトをトランザクションのスコープ内で実行しなければならない場合に、このオプションを選択します。新しいオブジェクトが作成されると、そのオブジェクト コンテキストはクライアントのコンテキストからトランザクションを継承します。クライアントにトランザクションがない場合、MTS は自動的にオブジェクトの新しいトランザクションを作成します。

•	[新しいトランザクションが必要] ─ コンポーネントのオブジェクトをオブジェクト自体のトランザクション内で実行しなければならない場合に、このオプションを選択します。新しいオブジェクトが作成されると、クライアントにトランザクションがあるかどうかに関係なく、MTS は "自動的に" オブジェクトの新しいトランザクションを作成します。

•	[トランザクションをサポートする] ─ コンポーネントのオブジェクトをクライアントのトランザクションのスコープ内で実行できる場合に、このオプションを選択します。新しいオブジェクトが作成されると、そのオブジェクト コンテキストはクライアントのコンテキストからトランザクションを継承します。クライアントにトランザクションがない場合は、新しいコンテキストもトランザクションなしで作成されます。

•	[トランザクションをサポートしない] ─ コンポーネントのオブジェクトをトランザクションのスコープ内で実行してはならない場合に、このオプションを選択します。新しいオブジェクトが作成されると、クライアントにトランザクションがあるかどうかに関係なく、トランザクションのないオブジェクト コンテキストが作成されます。

関連項目

[コンポーネント] フォルダ、コンポーネントのプロパティ、MTS トランザクションの管理


リモート コンポーネントのプロパティ

リモート コンポーネントのプロパティは、[リモート コンポーネント] フォルダに追加されたコンポーネントに関する情報を表示するときに使います。[全般] タブにコンポーネントの説明を入力する場合以外は、リモート コンポーネントのプロパティを構成することはできません。

[全般] タブ

関連項目

[リモート コンポーネント] フォルダ、MTS パッケージの配布


[全般] タブ (リモート コンポーネント)

[全般] タブには、選択されているリモート コンポーネントに関する識別情報が表示されます。

名前

リモート コンポーネントの名前が表示されます。

[説明]

リモート コンポーネントの説明が表示されます。リモート コンポーネントの識別と管理に役立つ説明を入力することができます。

[CLSID]

コンポーネントのクラス ID です。

[実行環境]

コンポーネントのインストール元のコンピュータ名を識別します。

関連項目

[リモート コンポーネント] フォルダ


ロールのプロパティ

ロールのプロパティは、特定のロールの名前、説明、およびロール ID を表示するときに使います。

[全般] タブ

関連項目

[ロール] フォルダ、MTS パッケージ セキュリティを有効にする、MTS ロールをユーザーとグループにマップする


[全般] タブ (ロール)

[全般] タブには、選択されているロールに関する全般的な情報が表示されます。

名前

ロールの名前が表示されます。

[説明]

ロールの説明が表示されます。ロールの識別と管理に役立つ説明を入力することができます。

[ロール ID]

ロールを追加するときに MTS が生成するロール ID 番号が表示されます。この番号を使って、別のパッケージに指定した同じ名前のロールを区別することができます。

[ロール] フォルダ内のオブジェクトとロール レベルで実行する操作の概要については、「[ロール] フォルダ」を参照してください。

関連項目

[ロール] フォルダ、ロールのプロパティ、MTS パッケージ セキュリティを有効にする、MTS ロールをユーザーとグループにマップする


ロール メンバのプロパティ

ロール メンバのプロパティは、コンポーネントまたはインターフェイスに追加されたロールに関する情報を表示するときに使います。

[全般] タブ

関連項目

[ロール メンバーシップ] フォルダ、MTS パッケージ セキュリティを有効にする、MTS ロールをユーザーとグループにマップする


[全般] タブ (ロール メンバ)

[全般] タブには、選択されているロールに関する全般的な情報が表示されます。

名前

ロールの名前が表示されます。

[説明]

ロールの説明が表示されます。

[ロール ID]

ロールを追加するときに MTS が生成するロール ID 番号が表示されます。この番号を使って、別のパッケージに指定した同じ名前のロールを区別することができます。

関連項目

[ロール メンバーシップ] フォルダ、ロールのプロパティ、MTS パッケージ セキュリティを有効にする、MTS ロールをユーザーとグループにマップする


インターフェイスのプロパティ

インターフェイスのプロパティは、コンポーネントが公開するインターフェイスに関する情報を表示するときに使います。

[全般] タブ

[プロキシ] タブ

関連項目

[インターフェイス] フォルダ


[全般] タブ (インターフェイス)

[全般] タブには、選択されているインターフェイスに関する全般的な情報が表示されます。

名前

インターフェイスの名前が表示されます。

[説明]

インターフェイスの説明が表示されます。インターフェイスの識別と管理に役立つ説明を入力することができます。

[IID]

インターフェイス ID 番号が表示されます。

関連項目

[インターフェイス] フォルダ、インターフェイスのプロパティ


[プロキシ] タブ (インターフェイス)

選択されているプロキシ/スタブに関する識別情報が表示されます。

[プロキシ/スタブ]

プロキシ/スタブ DLL のクラス ID (CLSID) とファイル名が表示されます。

[タイプ ライブラリ]

タイプ ライブラリのライブラリ ID とファイルの場所が表示されます。

関連項目

[インターフェイス] フォルダ、インターフェイスのプロパティ


メソッドのプロパティ

メソッドのプロパティは、インターフェイスが公開するメソッドに関する情報を表示するときに使います。

[全般] タブ

関連項目

[メソッド] フォルダ


[全般] タブ (メソッド)

[全般] タブには、選択されているメソッドに関する識別情報が表示されます。

名前

メソッドの名前が表示されます。

[説明]

メソッドの説明が表示されます。メソッドの識別と管理に役立つ説明を入力することができます。

関連項目

[メソッド] フォルダ、メソッドのプロパティ


MTS パッケージの作成

パッケージの作成は MTS アプリケーションの開発過程の最終段階で行われます。パッケージをどう設計するかによって、コンポーネントの構成とプロパティが規定されます。MTS パッケージを作成するには、プログラミングの知識は必要ありませんが、アプリケーションの設計仕様と実装仕様については熟知しておいてください。

Microsoft Transaction Server エクスプローラを使ってコンポーネントをパッケージに組み込むことが設計時にどのような意味を持つかについて理解するために、『管理者ガイド』のこのセクションを『Programmer's Guide』と併せて読むことを強くお勧めします。

コンポーネントのパッケージへの組み込みは、リソース プーリング、アクティブ化の設定、トランザクションのサポートなどの開発に関する決定事項を規定します。たとえば、パッケージを作成するときは、リソースを共有する複数のコンポーネントを同じパッケージにまとめてください。また、パッケージ内でコンポーネントが共有するリソースの種類を考慮し、特定のデータベースへの接続のように "高価な" リソースを共有するコンポーネントは 1 つのパッケージにまとめてください。

コンポーネントをパッケージに組み込むときにリソース プーリングを利用すると、より効率的な MTS アプリケーションを開発することができます。『Programmer's Guide』を『管理者ガイド』と併せて読むと、MTS エクスプローラを使ってパッケージを作成し、配置するために考慮する必要がある開発上の留意点について、より深く理解することができます。『Programmer's Guide』の入手方法については、「開発者用サンプルとドキュメントのインストール」を参照してください。

ここでは、次のトピックについて説明します。

空の MTS パッケージを作成する

MTS パッケージにコンポーネントを追加する

MTS コンポーネントをパッケージにインポートする

MTS パッケージからコンポーネントを削除する

エクスポート用の MTS パッケージを作成する

MTS パッケージのプロパティを設定する

MTS アクティブ化のプロパティを設定する

MTS トランザクションのプロパティを設定する

MTS 認証レベルを設定する

MTS パッケージをロックする


空の MTS パッケージを作成する

MTS エクスプローラを使用するときの最初のステップはパッケージの作成です。パッケージは同じプロセスで実行されるコンポーネントの集まりで、MTS エクスプローラを使って簡単に作成できます。空のパッケージを作成し、後からコンポーネントを追加するか、または既成のパッケージをインストールすることができます。パッケージを追加するには、パッケージ ウィザードを使うか、またはパッケージ ファイル (.pak) を Windows の エクスプローラからドラッグして MTS エクスプローラのウィンドウの右側にドロップします。

パッケージはサーバー コンピュータで実行しているサーバー プロセスの境界を定義します。たとえば、販売のコンポーネントと購入のコンポーネントを異なる 2 つのパッケージに分けると、これらの 2 つのコンポーネントは、プロセス分離性を保ちながら別々のプロセスで実行されます。したがって、一方のサーバー プロセスが (アプリケーションの致命的なエラーなどによって) 突然終了しても、もう一方のパッケージは別のプロセスで実行を継続できます。

空のパッケージを作成するには

1	MTS エクスプローラのウィンドウの左側で、パッケージを作成するコンピュータを選択します。

2	選択したコンピュータの [インストールされたパッケージ] フォルダを開きます。

3	次のいずれかの方法でパッケージ ウィザードを開きます。

•	[動作] メニューの [新規作成] をポイントし、[パッケージ] をクリックします。

•	[インストールされたパッケージ] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[パッケージ] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

4	パッケージ ウィザードを使って、既成のパッケージをインストールするか、または空のパッケージを作成します。空のパッケージを作成する場合、パッケージを機能させるには、コンポーネントとロールを追加しなければなりません。

5	[空のパッケージを作成する] をクリックします。

6	新しいパッケージの名前を入力し、[次へ] をクリックします。

7	[パッケージ ID の設定] ダイアログ ボックスでパッケージ ID を指定し、[完了] をクリックします。

既定の設定では、パッケージ ID として [対話ユーザー - 現在ログオンしているユーザー] が選択されます。対話ユーザーは、パッケージが実行されているサーバー コンピュータにログオンしたユーザーです。別のユーザーを選択するには、[このユーザー] を選択し、特定の Windows NT ユーザーを入力します。

関連項目

MTS パッケージにコンポーネントを追加する、MTS コンポーネントをパッケージにインポートする、エクスポート用の MTS パッケージを作成する, MTS パッケージ セキュリティを有効にする


MTS パッケージにコンポーネントを追加する

MTS コンポーネントは、コンポーネント オブジェクト モデル (COM) の仕様に準拠して作成される再利用可能なコードとデータです。コンポーネントはアプリケーションのビジネス ロジックを規定します。

コンポーネントをパッケージに追加するには、次のいずれかの操作を実行します。

•	コンポーネント ウィザードを使う。

•	既存のパッケージからコンポーネントを移動する。

パッケージの [コンポーネント] フォルダにコンポーネントを追加するには、MTS エクスプローラでコンポーネント ウィザードを使うか、または追加するコンポーネントを含むダイナミック リンク ライブラリ (DLL) を Windows NT エクスプローラからドラッグしてパッケージにドロップします。コンポーネント ウィザードを使う場合は、新しいコンポーネントをインストールし、そのコンポーネントをシステム レジストリに追加するか、または既に登録されているコンポーネントをインポートします。コンポーネントは空のパッケージまたは既存のパッケージに追加できます。

複数のパッケージにインストールできる複数のコンポーネントを、単一の MTS アプリケーションに含めることができます。つまり、同じ DLL に含まれている異なるコンポーネントをまったく別々のパッケージに組み込むことができます。

パッケージにコンポーネントを追加するには

1	MTS エクスプローラのウィンドウの左側で、コンポーネントをインストールするコンピュータを選択します。

2	[インストールされたパッケージ] フォルダを開き、コンポーネントをインストールするパッケージを選択します。

3	[コンポーネント] フォルダを開きます。

4	次のいずれかの方法でコンポーネント ウィザードを開きます。

•	[動作] メニューの [新規作成] をポイントし、[コンポーネント] をクリックします。

•	[コンポーネント] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[コンポーネント] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

5	[新しいコンポーネントをインストールする] をクリックします。

6	表示されたダイアログ ボックスで [ファイルの追加] をクリックし、インストールするファイルを選択します。インストールするコンポーネントが含まれる DLL を選択してください。コンポーネントに外部のタイプ ライブラリやプロキシ/スタブ DLL がある場合は、それらのファイルも追加します。Windows NT エクスプローラで、[ファイルの表示] の設定が [次の種類のファイルは隠す] ではなく [すべてのファイルを表示] に設定されていることを確認してください。このオプションが .dll 拡張子の付いたファイルを表示しない設定になっていると、[インストールするファイルの選択] ダイアログ ボックスにはコンポーネントを含む DLL が表示されません。この設定を変更した場合は、MTS エクスプローラを再起動する必要があります。

7	表示されたダイアログ ボックスで、追加するファイルを選択し、[開く] をクリックします。[ファイルの種類] ボックスで目的のファイルの種類をクリックすると、利用可能なすべてのファイル、DLL だけ、またはタイプ ライブラリだけを表示することができます。

8	ファイルを追加すると、[コンポーネントのインストール] ダイアログ ボックスに、追加したファイルと関連するコンポーネントが表示されます。[詳細] チェック ボックスをオンにすると、検出されたファイルの内容やコンポーネントについての詳細な情報が表示されます。Microsoft Transaction Server のコンポーネントには、タイプ ライブラリが必要です。コンポーネントのタイプ ライブラリが見つからない場合、一覧にはコンポーネントが表示されません。なお、[インストールするファイル] ボックスの一覧からファイルを削除するには、削除するファイルを選択し、[ファイルの削除] をクリックします。

9	[完了] をクリックし、コンポーネントをインストールします。コンポーネントをインストールすると、そのコンポーネントのインターフェイスとメソッドを見ることができます。コンポーネントをインポートした場合は、MTS エクスプローラにインターフェイスとメソッドは表示されません。

関連項目

空の MTS パッケージを作成する、MTS コンポーネントをパッケージにインポートする、MTS パッケージからコンポーネントを削除する、エクスポート用の MTS パッケージを作成する


MTS コンポーネントをパッケージにインポートする

COM (コンポーネント オブジェクト モデル) コンポーネントとして既にコンピュータに登録されている特定のコンポーネントを、Microsoft Transaction Server エクスプローラを使ってパッケージにインポートすることができます。コンポーネントをインポートした場合は、インターフェイスのプロパティを設定したり、リモート クライアントからコンポーネントへのアクセスを構成したりするのに必要なインターフェイスやメソッドの情報はインストールされません。コンポーネントはできるだけインポートしないでインストールしてください。

コンポーネントをパッケージにインポートするには

1	MTS エクスプローラのウィンドウの左側で、コンポーネントをインポートするコンピュータを選択します。

2	[インストールされたパッケージ] フォルダを開き、コンポーネントをインポートするパッケージを選択します。

3	[コンポーネント] フォルダを開きます。

4	次のいずれかの方法でコンポーネント ウィザードを開きます。

•	[動作] メニューの [新規作成] をポイントし、[コンポーネント] をクリックします。

•	[コンポーネント] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[コンポーネント] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

5	[既に登録されているコンポーネントをインポートする] をクリックします。

6	インポートするコンポーネントを選択します。

7	[完了] をクリックします。

関連情報

空の MTS パッケージを作成する、MTS パッケージにコンポーネントを追加する


MTS パッケージからコンポーネントを削除する

Microsoft Transaction Server エクスプローラを使って、パッケージからコンポーネントを削除することができます。コンポーネントを削除した後の状態は、コンポーネントを MTS ランタイム環境に追加した方法によって異なります。コンポーネントをインストールした場合は、コンポーネントを削除すると MTS ランタイム環境とコンピュータの両方からレジストリ情報が完全に削除されます。コンポーネントをインポートした場合、コンポーネントは MTS ランタイム環境から削除されますが、配置先のコンピュータには COM (コンポーネント オブジェクト モデル) コンポーネントとして登録されたまま残ります。この場合は、配置先のコンピュータから COM コンポーネントのレジストリ エントリとコンポーネント ファイルを手動で削除しなければなりません。

コンポーネントをパッケージから削除するには

1	エクスプローラのウィンドウの右側で、削除するコンポーネントを含むパッケージを選択します。

2	[コンポーネント] フォルダを開きます。

3	削除するコンポーネントを選択します。

4	次のいずれかの操作を実行します。

•	[動作] メニューの [削除] をクリックします。

•	削除するコンポーネントをマウスの右ボタンでクリックし、[削除] をクリックします。

•	MTS ツール バーの [削除] ボタンをクリックします。

5	表示されたダイアログ ボックスで [はい] をクリックします。

関連情報

空の MTS パッケージを作成する


エクスポート用の MTS パッケージを作成する

パッケージをエクスポートするには、MTS がサーバー コンピュータまたはクライアント コンピュータへのパッケージの登録を自動化できるようにコンポーネントを適切に構成しなければなりません。したがって、パッケージを作成するときは、パッケージを配布する方法を考慮してください。

Microsoft Transaction Server エクスプローラのパッケージ エクスポート機能を使って、MTS が動作しているほかのサーバー コンピュータにパッケージをエクスポートすることができます。また、Windows NT または Windows 95/98 が動作しているリモートのクライアント コンピュータがサーバー アプリケーションにアクセスするための、アプリケーションの実行可能ファイルを生成することもできます。パッケージを作成し、構成するときは、パッケージのエクスポートの必要条件を考慮してください。

アプリケーションの実行可能ファイルは、既定の設定では、実行可能ファイルが生成されたリモート MTS サーバーにアクセスするようにクライアント コンピュータを構成します。クライアント コンピュータの [プロパティ] ダイアログ ボックスの [オプション] タブを構成することによって、サーバー アプリケーションの場所を変更できます。実行可能ファイルを生成する前に、MTS エクスプローラの [マイ コンピュータ] アイコンをマウスの右ボタンでクリックし、[プロパティ] をクリックします。次に、[オプション] タブをクリックし、クライアント コンピュータがアクセスするサーバーのコンピュータ名を [リモート サーバー名] ボックスに入力します。入力するコンピュータ名は、パッケージを実行する MTS サーバーの名前にしなければなりません。次に、[OK] をクリックします。クライアント実行可能ファイルを生成すると、生成された実行可能ファイルは [リモート サーバー名] ボックスで指定したサーバーにアクセスするようにクライアントを構成します。これにより、複数のクライアントが同じパッケージを実行する複数のコンピュータをアクセスするようにして、静的にアプリケーションの負荷のバランスを取ることができます。

パッケージのエクスポートの必要条件

パッケージ開発者、またはパッケージを配置する上級システム管理者や上級 Web 管理者は、MTS パッケージの作成と配置を行うときに、次の必要条件を順守しなければなりません。

•	クライアント インストール ユーティリティは、言語に依存しないリソースを使ってコンポーネントのバージョン番号を判断します。Visual C++ コンポーネントの場合、言語に依存するリソースと同様に、言語に依存しないリソースのアプリケーション バージョン番号を変更する必要があります。言語に依存しないリソースを変更しない場合、クライアント実行可能ファイルは、より新しいバージョンをコンポーネントの期限の切れたバージョンで上書きする可能性があります。

•	クライアント専用アプリケーションのタイプ ライブラリから標準 COM インターフェイスの記述を削除します。たとえば、パッケージ開発者はインターフェイスを Visual Basic で使用するために IObjectSafety などのインターフェイスをタイプ ライブラリで定義していることがあります。エクスポートする前にインターフェイスの記述を削除すると、クライアント コンピュータでそのインターフェイスが不適切に登録されたり、登録を削除されたりすることを防止できます。クライアント専用タイプ ライブラリから標準 COM インターフェイスの記述を削除しないと、これらの標準インターフェイスを使用するほかのアプリケーションに障害が発生する場合があります。

•	サーバー パッケージ内にあり、クライアントが使用している (クラス ID、インターフェイス ID、タイプ ライブラリ ID を含む) グローバルに一意識別子 (GUID) のいずれかが変更された場合、クライアント インストール実行可能ファイルを更新するには、パッケージを再エクスポートする必要があります。アプリケーションのクライアントは、新しいクライアント インストール実行可能ファイルを実行するまで、サーバー アプリケーションにアクセスできません。一部の開発ツール （Microsoftｮ Visual Basicｮ など） では、開発者に通知せずにこれらの GUID を変更する可能性があることに注意してください。

MTS エクスプローラを使って MTS パッケージを配布する方法の詳細については、「MTS パッケージの配布」を参照してください。

関連項目

空の MTS パッケージを作成する、MTS パッケージにコンポーネントを追加する、MTS コンポーネントをパッケージにインポートする


MTS パッケージのプロパティを設定する

パッケージのプロパティは、パッケージの構成を規定します。パッケージの[プロパティ] ダイアログ ボックスを表示するには、Microsoft Transaction Server エクスプローラで、パッケージをマウスの右ボタンでクリックし、[プロパティ] をクリックするか、またはパッケージを選択し、[動作] メニューの [プロパティ] をクリックします。

パッケージの [プロパティ] ダイアログ ボックスには、次の 5 つのタブがあります。

•	[全般] タブ

パッケージの名前と説明が表示されます。

•	[セキュリティ] タブ

認証の確認を有効にします。セキュリティの既定の設定では、認証の確認は有効になっていません。詳細については、「MTS パッケージ セキュリティを有効にする」を参照してください。

•	[詳細設定] タブ

パッケージに関連付けられているサーバー プロセスを常に実行するか、または一定の時間が経過したらシャットダウンするかを指定します。

•	[ID] タブ

パッケージにアクセスできるユーザーを設定します。既定値は [対話ユーザー - 現在ログオンしているユーザー] です。この設定は、現在 Windows NT Server のアカウントにログオンしているユーザーです。ほかのユーザーを選択する場合は、[このユーザー] を選択し、アカウント名とパスワードを指定します。

•	[アクティブ化] タブ

パッケージとパッケージのコンポーネントのアクティブ化レベルを設定します。アクティブ化レベルは、コンポーネントが作成元のプロセスでアクティブ化される [ライブラリ パッケージ]、またはパッケージが専用のサーバー プロセスで実行される [サーバー パッケージ]のいずれかに設定できます。

詳細については、「MTS アクティブ化のプロパティを設定する」を参照してください。

パッケージまたはコンポーネントのプロパティを変更するには、[プロパティ] ダイアログ ボックスを使わなければなりません。

[プロパティ] ダイアログ ボックスを表示するには

1	構成するパッケージまたはコンポーネントをマウスの右ボタンでクリックし、[プロパティ] をクリックします。または、目的のアイテムを選択し、[動作] メニューの [プロパティ] をクリックします。

2	目的のタブをクリックします。

3	プロパティの設定を更新します。

4	[OK] をクリックして設定を保存し、MTS エクスプローラに戻ります。

コンポーネントの設定を更新する

プロジェクトを再コンパイルするたびに、コンポーネントの設定を更新することが重要です。コンポーネントの設定を更新すると、コンポーネントのレジストリ設定の書き替えを防止できます。

 コンポーネントの設定を更新するには

1	MTS エクスプローラのウィンドウの左側で、更新するコンポーネントが含まれるコンピュータを選択します。

2	[動作] メニューの [すべてのコンポーネントの更新] をクリックします。Transaction Server が更新され、システム レジストリ、コンポーネント の CLSID、またはインターフェイス ID (IID) の変更が反映されます。コンポーネントを更新するには、エクスプローラのウィンドウの左側でコンピュータを選択し、MTS ツール バーの [最新の情報に更新] ボタンをクリックする方法もあります。

[すべてのコンポーネントの更新] コマンドは、MTS エクスプローラの階層でコンピュータを選択した場合にのみ使用できます。このコマンドは、選択されたコンピュータに適用されます。

関連項目

MTS アクティブ化のプロパティを設定する、MTS トランザクションのプロパティを設定する、MTS 認証レベルを設定する、MTS パッケージをロックする


MTS アクティブ化のプロパティを設定する

アクティブ化のプロパティは、パッケージを設計するときに指定してください。パッケージは、呼び出したクライアントのプロセス内で実行されるように (ライブラリ パッケージとして) 設定するか、または専用のサーバー プロセス内で実行されるように (サーバー パッケージとして) 設定することができます。

[ライブラリ パッケージ]

パッケージをライブラリ パッケージとして実行するには、このオプションを選択します。ライブラリ パッケージは、パッケージの作成元クライアントのプロセス内で実行されます。このオプションは、パッケージがインストールされ、構成されているコンピュータ上のクライアントでだけ選択できます。ライブラリ パッケージは、コンポーネントの追跡、ロールのチェック、プロセスの分離を行いません。

[サーバー パッケージ]

パッケージをサーバー パッケージとして実行するには、このオプションを選択します。サーバー パッケージは、ローカル コンピュータ上のサーバー パッケージ自体のプロセス内で実行されます。サーバー パッケージは、ロールに基づくセキュリティ、リソースの共有、プロセスの分離、(パッケージの追跡などの) プロセス管理をサポートします。

パッケージのアクティブ化のプロパティを設定するには

1	構成するパッケージを選択します。

2	次のいずれかの方法で [プロパティ] ダイアログ ボックスの [アクティブ化] タブを表示します。

•	[動作] メニューの [プロパティ] をクリックし、[アクティブ化] タブをクリックします。

•	構成するパッケージをマウスの右ボタンでクリックし、[プロパティ] をクリックします。次に [アクティブ化] タブをクリックします。

•	MTS ツール バーの [プロパティ] ボタンをクリックします。次に [アクティブ化] タブをクリックします。

3	適切なアクティブ化のプロパティを指定します。

4	[OK] をクリックして MTS エクスプローラに戻ります。

関連項目

MTS パッケージのプロパティを設定する、MTS トランザクションのプロパティを設定する、MTS 認証レベルを設定する、MTS パッケージをロックする


MTS トランザクションのプロパティを設定する

アプリケーションがトランザクションをサポートするかどうかは、設計時に指定してください。サポートする場合は、配置を行うときに Microsoft Transaction Server エクスプローラを使ってコンポーネントのトランザクションのプロパティを設定してください。[プロパティ] ダイアログ ボックスの [トランザクション] タブでは、コンポーネントがトランザクションをサポートする方法を指定します。コンポーネントのトランザクションのプロパティとして、次の設定のいずれかを選択できます。

•	[トランザクションが必要]   コンポーネントのオブジェクトをトランザクションのスコープ内で実行する必要がある場合に、このオプションを選択します。新しいオブジェクトが作成されると、そのオブジェクト コンテキストはクライアントのコンテキストからトランザクションを継承します。クライアントにトランザクションがない場合、MTS は自動的にオブジェクトの新しいトランザクションを作成します。

•	[新しいトランザクションが必要]   コンポーネントのオブジェクトをオブジェクト自体のトランザクション内で実行する必要がある場合に、このオプションを選択します。新しいオブジェクトが作成されると、クライアントにトランザクションがあるかどうかに関係なく、MTS は自動的にオブジェクトの新しいトランザクションを作成します。

•	[トランザクションをサポートする]   コンポーネントのオブジェクトをクライアントのトランザクションのスコープ内で実行できる場合に、このオプションを選択します。新しいオブジェクトが作成されると、そのオブジェクト コンテキストはクライアントのコンテキストからトランザクションを継承します。クライアントにトランザクションがない場合は、新しいコンテキストもトランザクションなしで作成されます。

•	[トランザクションをサポートしない]   コンポーネントのオブジェクトをトランザクションのスコープ内で実行してはならない場合に、このオプションを選択します。新しいオブジェクトが作成されると、クライアントにトランザクションがあるかどうかに関係なく、トランザクションのないオブジェクト コンテキストが作成されます。

コンポーネントのインスタンスが作成されるたびに、MTS はコンポーネントのトランザクション属性をチェックし、インスタンスをトランザクション内で実行するかどうかを決定します。

すべてのコンポーネントがトランザクション処理をサポートするように設計されているわけではありません。コンポーネントがトランザクション処理を使用するように設計されていない場合は、コンポーネントの [プロパティ] ダイアログ ボックスの [トランザクション] タブで、トランザクション属性を必ず [トランザクションをサポートしない] に設定してください。

パッケージ内のコンポーネントが "ロック" されている場合は、トランザクション属性を変更できません。詳細については、「MTS パッケージをロックする」を参照してください。

コンポーネントのトランザクションのプロパティを設定するには

1	構成するコンポーネントを選択します。

2	次のいずれかの方法で [プロパティ] ダイアログ ボックスの [トランザクション] タブを表示します。

•	[動作] メニューの [プロパティ] をクリックし、[トランザクション] タブをクリックします。

•	構成するコンポーネントをマウスの右ボタンでクリックし、[プロパティ] をクリックします。次に [トランザクション] タブをクリックします。

•	MTS ツール バーの [プロパティ] ボタンをクリックします。次に [トランザクション] タブをクリックします。

3	適切なトランザクション属性のオプションをクリックします。

4	[OK] をクリックします。

分散トランザクションの概要およびトランザクションを監視し、管理する方法については、「MTS トランザクションの管理」を参照してください。

関連項目

MTS パッケージのプロパティを設定する、MTS アクティブ化のプロパティを設定する、MTS 認証レベルを設定する、MTS パッケージをロックする


MTS 認証レベルを設定する

アプリケーションの認証レベルは、クライアントからの要求を認証するためのセキュリティのレベルを示します。アプリケーションのクライアントに認証を要求しない場合は、パッケージの[プロパティ] ダイアログ ボックスの [セキュリティ] タブで、[認証の確認を実行する] チェック ボックスをオンにします。

DCOM 認証レベルについて完全に理解している場合以外は、パッケージの認証の設定を MTS の既定の設定である [パケット] レベルのままにしておくことをお勧めします。

DCOM 認証の設定について次に説明します。

レベル	説明
[なし]	このパッケージと別のパッケージ、またはクライアント アプリケーションとの間の通信では、セキュリティ チェックは行われません。
[接続]	最初の接続時にだけセキュリティ チェックが行われます。
[呼び出し]	接続状態が続いている間は、すべての呼び出しに対してセキュリティ チェックが行われます。
[パケット]	送信元の ID が暗号化されます。
[パケットの整合性]	転送中にパケットが変更されていないことを確認するために、送信元の ID と署名が暗号化されます。
[パケットのプライバシー]	セキュリティを最大限にするために、データ、および送信元の ID と署名を含むパケット全体が暗号化されます。
コンピュータの認証レベルを設定するには

1	MTS エクスプローラで、構成するパッケージを選択します。

2	次のいずれかの方法で [プロパティ] ダイアログ ボックスの [セキュリティ] タブを表示します。

•	[動作] メニューの [プロパティ] をクリックし、[セキュリティ] タブをクリックします。

•	構成するパッケージをマウスの右ボタンでクリックし、[プロパティ] をクリックします。次に [セキュリティ] タブをクリックします。

•	MTS ツール バーの [プロパティ] ボタンをクリックします。次に [セキュリティ] タブをクリックします。

3	[呼び出しの認証レベル] ボックスで、このパッケージに構成する認証レベルを選択します。

4	[OK] をクリックします。

関連項目

MTS パッケージのプロパティを設定する、MTS アクティブ化のプロパティを設定する、MTS トランザクションのプロパティを設定する、MTS パッケージをロックする


MTS パッケージをロックする

アプリケーションの開発、インストール、または配置が完了したら、コンポーネントの構成が変更されないようにパッケージをロックすることを考慮してください。システム管理者または Web 管理者が管理しているほかの MTS コンピュータにサーバー アプリケーションをエクスポートする前に、またはサーバー アプリケーションを顧客に配布する前に、作成したパッケージをロックすることができます。

パッケージのロックは、次の操作に適用できます。

•	変更

この操作をロックすると、管理者はロックを無効にしないとパッケージの構成を変更できません。

•	削除

この操作をロックすると、管理者はロックを無効にしないとパッケージを削除できません。

パッケージをロックするには

1	パッケージの構成が完了したら、パッケージの [プロパティ] ダイアログ ボックスの [詳細設定] タブをクリックします。

2	[詳細設定] タブの [アクセス権] で、ユーザーによるパッケージの削除を禁止する [削除を無効にする] チェック ボックス、およびユーザーによるパッケージのプロパティの変更を禁止する [変更を無効にする] チェック ボックスの両方、またはいずれかをオンにします。

[詳細設定] タブで、チェック ボックスをオフにすると、パッケージのロックを解除できます。

関連項目

MTS パッケージのプロパティを設定する、MTS アクティブ化のプロパティを設定する、MTS トランザクションのプロパティを設定する、MTS 認証レベルを設定する


MTS パッケージの配布

Microsoft Transaction Server エクスプローラを使って、MTS を実行しているクライアントにも、実行していないクライアントにもパッケージを配布できます。クライアント コンピュータとサーバー コンピュータの両方で MTS を実行している場合は、MTS エクスプローラを使って、アプリケーション実行可能ファイルの作成や [リモート コンポーネント] フォルダを利用したコンポーネントのプッシュまたはプルを行うことができます。クライアント コンピュータで MTS を実行していない場合は、MTS エクスプローラを使って、クライアントから DCOM 経由でリモート MTS サーバー アプリケーションにアクセスできるようにクライアントを自動的にインストールし、構成するアプリケーション実行可能ファイルを生成します。

ここでは、次のトピックについて説明します。

リモート MTS コンピュータを使う

MTS パッケージのエクスポート

MTS 実行可能ファイルを生成する

関連項目

[リモート コンポーネント] フォルダ


リモート MTS コンピュータを使う

サーバー コンピュータとクライアント コンピュータの両方で MTS を実行している場合は、複数のコンピュータ間でコンポーネントの "プル" と "プッシュ" を行うことによって、パッケージを配布することができます。また、Microsoft Transaction Server エクスプローラでアプリケーション実行可能ファイル ユーティリティを使って、アプリケーション実行可能ファイルを生成することもできます。MTS エクスプローラを使ってアプリケーション実行可能ファイルを生成する方法の詳細については、「MTS 実行可能ファイルを生成する」を参照してください。

コンポーネントのプッシュとは、リモート コンピュータにリモート コンポーネント エントリを作成することを意味します。リモート コンポーネント エントリが作成されたら、これらのコンポーネント エントリをローカル コンピュータの [リモート コンポーネント] フォルダに追加する必要があります （コンポーネントのプル)。

次の図は、コンポーネントのプッシュとプルによって MTS を実行しているリモート コンピュータを構成する仕組みを示しています。

上の図では、MTS が 3 台のコンピュータすべてにインストールされています。GetReceipt と MoveMoney はいずれも、使用しているコンピュータ (サーバー A) のパッケージにインストールされています。サーバー B とサーバー C の [リモート コンポーネント] フォルダに GetReceipt コンポーネントと MoveMoney コンポーネントを追加すると、次の 2 つの処理が行われます。まず、適切な DLL ファイルがネットワーク経由でサーバー B とサーバー C にコピーされます。これらのファイルは、サーバー A のパッケージと同じ名前のサブディレクトリにコピーされます。このサブディレクトリは、\<Microsoft Transaction Server のインストール ディレクトリ>\Remote ディレクトリの下 (たとえば、C:\Program Files\Mts\Remote\Sample Bank) に作成されます。次に、サーバー B と サーバー C のシステム レジストリがサーバー A のシステム レジストリの情報によって更新されます。

DLL ファイルとタイプ ライブラリ ファイルの保存と配布のための共有ネットワーク ディレクトリが設定されている場合にだけ、コンポーネントのプッシュとプルを行うことができます (共有ディレクトリのフォルダまたはサブフォルダのいずれかにコンポーネント ファイルが含まれていれば、どの共有ディレクトリでも選択できます)。MTS エクスプローラは、サーバー上の利用可能な共有ネットワーク ディレクトリを自動的に探します。複数の共有ディレクトリを 1 つのサーバー上に作成し、異なるコンポーネント ファイルのセットにアクセスすることができます。

また、プッシュとプルを行うには、次の条件も満たされていなければなりません。

•	ターゲット コンピュータのシステム パッケージの Administrators ロールのメンバーになっている Windows NT アカウントを使ってログオンしていること。

•	ターゲット コンピュータのシステム パッケージ ID が、ローカルのシステム パッケージの Reader ロールに設定されている Windows NT アカウントにマップされていること。

•	両方のコンピュータでシステム パッケージのセキュリティが有効になっていること。詳細については、「MTS パッケージ セキュリティを有効にする」を参照してください。

コンポーネントをプッシュするには、まず適切な 1 台または複数のコンピュータを MTS エクスプローラに追加しなければなりません。MTS エクスプローラにコンピュータを追加する方法については、「MTS サーバーの構成」を参照してください。

次に、リモート コンピュータの [リモート コンポーネント] フォルダにコンポーネントを追加しなければなりません。

リモート コンピュータの [リモート コンポーネント] フォルダにコンポーネントを追加するには

1	[コンピュータ] フォルダを選択し、[動作] メニューの [新規作成] をポイントします。次に、[コンピュータ] をクリックしてリモート コンピュータを追加します。

2	追加するコンピュータの名前を入力し、[OK] をクリックします。コンピュータの名前がわからない場合は、[参照] をクリックしてコンピュータを選択します。

3	MTS エクスプローラで、リモート コンポーネントを追加するコンピュータの [リモート コンポーネント] フォルダを開きます。

4	次のいずれかの操作を実行します。

•	[動作] メニューの [新規作成] をポイントし、[リモート コンポーネント] をクリックします。

•	マウスの右ボタンで [リモート コンポーネント] フォルダをクリックし、[新規作成] をポイントします。次に、[リモート コンポーネント] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

5	表示されたダイアログ ボックスで、リモート コンピュータとリモートから呼び出すコンポーネントを含むパッケージを選択します。

6	[利用できるコンポーネント] ボックスの一覧で、リモートから呼び出すコンポーネントを選択し、下向き矢印 ([追加]) をクリックします。これにより、コンポーネントと、そのコンポーネントが保存されているコンピュータが [コンポーネントの構成場所] ボックスに追加されます。[詳細] チェック ボックスをオンにすると、リモート コンピュータ、パッケージ、および DLL のパスが [コンポーネントの構成場所] ボックスに表示されます。

7	[OK] をクリックします。

注   リモート コンピュータに保存されているコンポーネントを追加すると、必要なファイルが \<MTS インストール ディレクトリ>\remote ディレクトリに保存されます (既定の MTS インストール ディレクトリは \Program Files\MTS です)。

関連項目

[リモート コンポーネント] フォルダ


MTS パッケージのエクスポート

パッケージのエクスポートによって、ある MTS コンピュータから別の MTS コンピュータにパッケージをコピーできます。たとえば、パッケージをテストするために、Microsoft Transaction Server エクスプローラを使って、パッケージが開発されたサーバーから別の MTS サーバーにパッケージをエクスポートすることができます。

パッケージをエクスポートするには

1	MTS エクスプローラのウィンドウの左側で、エクスポートするパッケージを選択します。

2	[動作] メニューの [エクスポート] をクリックします。または、パッケージをマウスの右ボタンでクリックし、[エクスポート] をクリックします。

3	[パッケージのエクスポート] ダイアログ ボックスで、作成するパッケージ ファイルのパスと名前を入力するか、または [参照] をクリックしてファイルを指定します。コンポーネント ファイルは、パッケージ ファイルと同じディレクトリにコピーされます。

4	エクスポートするパッケージに、既にユーザーが割り当てられているパッケージのロールを含める場合は、[ロールに関連付けられた NT のユーザー ID を保存する] チェック ボックスをオンにします。

5	[エクスポート] をクリックします。

パッケージをエクスポートすると、Microsoft Transaction Server は、元のパッケージに含まれているコンポーネントと ([ロールに関連付けられた NT のユーザー ID を保存する] チェック ボックスをオンにした場合は) ロールに関する情報を含むパッケージ ファイル (拡張子 .pak) を作成し、パッケージに関連のあるコンポーネント ファイル (ダイナミック リンク ライブラリ (DLL)、タイプ ライブラリ、およびプロキシ/スタブ DLL) をパッケージ ファイルが作成されたディレクトリと同じディレクトリにコピーします。パッケージで設定されている変更および削除のロックは、パッケージと共にエクスポートされます。

重要  パッケージをエクスポートした後で、コンポーネントのクラス ID (CLSID)、タイプ ライブラリ ID (TypeLibId)、またはインターフェイス ID (IID) が変更された場合は、パッケージをもう一度エクスポートしなければなりません。

関連項目

エクスポート用の MTS パッケージを作成する、MTS パッケージをロックする、MTS ロールをユーザーとグループにマップする


MTS 実行可能ファイルを生成する

MTS エクスプローラを使って、リモート サーバー アプリケーションにアクセスできるようにクライアント コンピュータのインストールと構成を行うアプリケーションの実行可能ファイルを生成できます。実行可能ファイルをインストールするクライアント コンピュータは、DCOM をサポートしていなければなりません。ただし、リモート MTS サーバー アプリケーションにアクセスするには、実行可能ファイル以外の MTS サーバー ファイルは必要ありません。

アプリケーション実行可能ファイル ユーティリティは、MTS エクスプローラのパッケージ エクスポート機能の一部です。このユーティリティを使うと、クライアント アプリケーションをインストールし、リモート MTS サーバー上のサーバー アプリケーションにアクセスできるようにクライアント コンピュータを構成するアプリケーションの実行可能ファイルを自動的に生成できます。既定の設定では、アプリケーション実行可能ファイル ユーティリティによって生成される実行可能ファイルは、実行可能ファイルが生成されたサーバーにアクセスするようにクライアント コンピュータを構成します。

コンピュータの [プロパティ] ダイアログ ボックスの [オプション] タブの [リモート サーバー名] で、クライアント アプリケーションがアクセスするサーバーを指定することもできます。パッケージをエクスポートして実行可能ファイルを生成する前に、ほかのサーバー コンピュータの名前を入力しなければ、ローカル コンピュータで作成されるアプリケーションの実行可能ファイルは、自動的にローカル コンピュータ上のサーバー パッケージにアクセスするようにクライアント コンピュータを構成します。

ローカル コンピュータ以外のサーバー コンピュータにアクセスするようにクライアント アプリケーションの実行可能ファイルを構成するには

1	MTS エクスプローラのウィンドウの左側で、[マイ コンピュータ] アイコンを選択します。

2	[マイ コンピュータ] アイコンをマウスの右ボタンでクリックし、[プロパティ] をクリックします。

3	[オプション] タブを選択し、[レプリケーション] の [リモート サーバー名] ボックスにリモート サーバーの名前を入力します。

4	[OK] をクリックし、パッケージをエクスポートしてアプリケーションの実行可能ファイルを作成します。

アプリケーション実行可能ファイル ユーティリティがクライアント アプリケーションの実行可能ファイルを自動的に作成します。

クライアントでは、実行可能ファイルが次の作業を自動的に行います。

1	タイプ ライブラリとカスタム プロキシ/スタブ DLL を含む必要なクライアント側のファイルをクライアント コンピュータまたはサーバー コンピュータの一時ディレクトリにコピーし、取り出します。

2	サーバー アプリケーション用のタイプ ライブラリとプロキシ/スタブ DLL を \Program Files\Remote Applications ディレクトリに転送します。リモート アプリケーションには、パッケージのグローバルに一意の ID (GUID) と同じ名前のディレクトリが個別に作成され、そのディレクトリにファイルが保存されます。

3	クライアントがリモートからサーバー アプリケーションを使用できるようにする (アプリケーション、クラス、プログラム、インターフェイス、およびライブラリの ID に関連する情報を含む) エントリ、またはサーバー アプリケーションをサーバー コンピュータ上で実行できるようにするエントリによってシステム レジストリを更新します。

4	ユーザーがコントロール パネルの [アプリケーションの追加と削除] アイコンを使って、後からアプリケーションを削除できるように、アプリケーションを登録します。インストールされたコンポーネントの一覧で簡単に見分けがつくように、すべてのアプリケーションの前に "Remote Application" が付けられます。

5	アプリケーションのインストール中に生成された一時ディレクトリのファイルをすべて削除します。

クライアント コンピュータでクライアント実行可能ファイルが実行されると、必要なプロキシ/スタブ DLL とタイプ ライブラリがクライアント コンピュータにコピーされ、サーバー コンピュータ名を含む DCOM に必要な情報によってクライアントのシステム レジストリが更新されます。これにより、クライアント アプリケーションはリモート サーバー アプリケーションにアクセスできるようになります。

パッケージをエクスポートして実行可能ファイルを作成する前に、クライアント インストール ファイル (clients.ini) を作成することにより、クライアント アプリケーションのインストールをカスタマイズできます。clients.ini ファイルによって、数種類の異なるアプリケーション用のクライアント実行可能ファイルのインストールを組み合わせたり、アプリケーションのドキュメントを含めることもできます。

インストールをカスタマイズするには

1	clients.ini という名前のファイルを作成し、パッケージをエクスポートするフォルダに保存します。

2	次のテキストを空の clients.ini ファイルにコピーします。

[ClientApplicationFiles]

SourcePath=c:\temp\custom vb bank

[ClientApplicationInstallCommands]

1=notepad {{{readme.txt}}}

2={{{vbbank.exe}}}

[ClientApplicationSetup]

ExploreApplication=Y

3	見出し ClientApplicationFiles の下のパス指定を、クライアント コンピュータにインストールするソース コードがあるディレクトリに変更します。たとえば、次のように変更します。

SourcePath=c:\program files\mts\test\vb bank

4	見出し ClientApplicationInstallCommands の下には、インストールするファイルの名前を指定します。ファイル名は、3 重かっこで囲みます。たとえば、次のように指定します。

1=notepad {{{readme.txt}}}
2={{{vbbank.ex}}}}

インストールするファイルは、SourcePath= で指定したディレクトリに存在する必要があります。

5	見出し ClientApplicationSetup の下では、ExploreApplication セットアップ オプションを有効にするかどうかを示します。 ExploreApplication=Y を指定すると、セットアップの終了直後にエクスプローラが自動的に起動してインストールしたファイルを表示します。このオプションを使うと、クライアントがデスクトップ上にショートカットを作成するのに便利です。ExploreApplication=N を指定するか、[ClientApplicationSetup] セクションを指定しなかった場合は、エクスプローラは起動されません。

clients.ini ファイルを変更して保存したら、MTS エクスプローラを使ってサーバー パッケージをエクスポートし、クライアント実行可能ファイルを作成することができます。

クライアント実行可能ファイルを作成するには

1	サーバー アプリケーションをインストールしていない場合は、パッケージ ウィザードを使ってインストールします。

実行可能ファイルを作成する配置サーバー以外のサーバーをクライアントがアクセスする場合は、[マイ コンピュータ] アイコンをマウスの右ボタンでクリックし、[プロパティ] をクリックします。次に [オプション] タブをクリックして [リモート サーバー名] ボックスに、クライアントがアクセスするサーバーの名前を入力します。

3	パッケージをエクスポートします。パッケージをエクスポートするファイル名として新しいファイル名 (YourNewFileName) を指定します。

4	パッケージのエクスポート先フォルダを探します。"YourNewFileName.exe" という名前のファイルが 1 つ含まれている Clients ディレクトリがあることを確認します。MTS エクスプローラで既存のパッケージをエクスポートすると、パッケージのエクスポート先ディレクトリの下に Clients ディレクトリが作成されます。Clients ディレクトリには、パッケージをエクスポートするときに指定した名前の実行可能ファイルが 1 つ含まれています。DCOM をサポートしている任意のクライアントでこの実行可能ファイルが実行されると、リモート クライアントがサーバー アプリケーションにアクセスするために必要な情報がすべてインストールされます。

重要   サーバー コンピュータでこのクライアント実行可能ファイルを実行しないでください。クライアント実行可能ファイルをサーバー コンピュータで実行すると、サーバー パッケージの実行に必要なレジストリ エントリが削除されます。誤って実行した場合は、コントロール パネルの [アプリケーションの追加と削除] アイコンを使ってアプリケーションを削除しなければなりません。その後、MTS エクスプローラを使ってパッケージを削除し、再インストールします。

クライアント実行可能ファイルがインストールするコンポーネントのほかのバージョンがクライアント コンピュータに既に存在する場合、コンポーネントは次の場合にのみ更新されます。

•	コンポーネントの両方のバージョンがバージョン番号を持っている。

•	インストールされるコンポーネントのバージョンが、既にインストールされているコンポーネントのバージョンよりも後のバージョンである。

クライアント実行可能ファイルを配布する

MTS エクスプローラは、配布用の実行可能ファイルへのクライアント アプリケーションの実装と組み込みを自動化します。これらの実行可能ファイルは、次のいずれかの方法で配布します。

•	ディレクトリを共有し、クライアントが実行可能ファイルをコピーして、クライアントのコンピュータで実行できるようにする方法。

•	実行可能ファイルを電子メールの添付ファイルとして送信し、クライアントが実行可能ファイルを保存して、クライアントのコンピュータで実行できるようにする方法。

•	<OBJECT> タグを使って実行可能ファイルを HTML スクリプトに組み込む方法。<OBJECT> タグを使うと、クライアントが HTML ページで (ボタンをクリックするなどの) イベントを開始すれば、ブラウザを使って、指定されたオブジェクト格納場所からアプリケーションをクライアント コンピュータにダウンロードすることができます。<OBJECT> タグを使用して実行可能ファイルを配布すると、ブラウザは自動的にアプリケーションの現在のバージョンとクライアントのレジストリを照合するので、アップグレードが容易になります。既存の実行可能ファイルが以前のバージョンの場合、ブラウザはオブジェクト格納場所から最新のバージョンをダウンロードします。

•	Microsoft System Management Server (SMS) を使って、セントラル サイトから一度に何十台、何百台ものコンピュータにアプリケーションの配布を "プッシュ" する方法。アプリケーションをインストールした後、クライアント アプリケーション自体をリモート コンピュータにインストールしなければならないことに注意してください。

クライアント実行可能ファイルを削除する

クライアントは、コントロール パネルの [アプリケーションの追加と削除] アイコンを使ってクライアント実行可能ファイルを削除することができます。MTS 実行可能ファイルによってインストールされたアプリケーションは、[インストールと削除] タブ (Windows 95/98 では [セットアップと削除] タブ) の一覧に表示されるとき、先頭に "Remote Application" が付きます。実行可能ファイルを削除するには、目的のアプリケーションを選択し、[追加と削除] をクリックします。

関連項目

MTS パッケージのエクスポート、エクスポート用の MTS パッケージを作成する


MTS パッケージのインストール

MTS パッケージのインストールは、MTS エクスプローラを使って MTS ランタイム環境へパッケージをインストールし、配置することです。インストールと配置の手順は、適切なパッケージ ID の設定などの設計に関する考慮点と密接に関連しています。

アプリケーションを配置する前に、パッケージとパッケージのコンポーネントの構造を十分に理解してください。MTS コンポーネントの設計と作成の詳細については、『Programmer's Guide』を参照してください。

MTS エクスプローラを使って既成のパッケージを簡単に配置できます。ここでは、次のトピックについて説明します。

既成の MTS パッケージのインストール

MTS パッケージのアップグレード

MTS パッケージ セキュリティを有効にする

MTS パッケージ ID の設定

新しい MTS ロールの追加

MTS ロールをユーザーとグループにマップする

関連項目

[ID] タブ (パッケージ)、[インストールされたパッケージ] フォルダ、[ロール] フォルダ、[ユーザー] フォルダ、[ロール メンバーシップ] フォルダ、MTS ロールのユーザーを管理する


既成の MTS パッケージのインストール

既成のパッケージは、パッケージに関連するパッケージ ファイルとコンポーネント ファイル (ダイナミック リンク ライブラリ (DLL) とタイプ ライブラリ) から構成されています。MTS エクスプローラを使って、サード パーティまたは企業の開発部門によって作成された既成のパッケージのインストールと配置を行うことができます。

パッケージをインストールしたら、パッケージを構成するために、少なくとも、MTS によって保存されているオブジェクトへのアクセスの制御、ロールへのユーザーの割り当て、およびパッケージのセキュリティ レベルの設定を行う必要があります。パッケージのセキュリティを構成する方法の詳細については、「MTS パッケージ セキュリティを有効にする」を参照してください。

既成のパッケージをインストールするには

1	MTS エクスプローラのウィンドウの左側で、パッケージを作成するコンピュータを選択します。

2	選択したコンピュータの [インストールされたパッケージ] フォルダを開きます。

3	次のいずれかの方法で、パッケージ ウィザードを開きます。

•	[動作] メニューの [新規作成] をポイントし、[パッケージ] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

•	[インストールされたパッケージ] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[パッケージ] をクリックします。

4	[既成のパッケージをインストールする] をクリックします。

5	[パッケージ ファイルの選択] ダイアログ ボックスで、[追加] をクリックしてネットワーク上の利用できるパッケージ ファイルを探します。パッケージ ファイル (.pak) を選択し、[開く] をクリックします。次に、[次へ] をクリックします。同時に複数のパッケージをインストールできます。パッケージに含まれているコンポーネント ファイルは、パッケージ ファイルと同じディレクトリに置かれていなければなりません。

6	[パッケージ ID の設定] ダイアログ ボックスで、パッケージ ID を指定し、[次へ] をクリックします。既定の設定では [対話ユーザー - 現在ログオンしているユーザー] が選択されます。対話ユーザーは、パッケージが実行されるコンピュータの Windows NT アカウントにログオンしたユーザーです。別のユーザーを選択するには、[このユーザー] を選択し、特定の Windows NT ユーザーの詳細情報を入力します。

7	[インストール オプション] ダイアログ ボックスで、インストール先ディレクトリを指定します。コンポーネント ファイルが、パッケージ ファイルのディレクトリからインストール先ディレクトリにコピーされます。既定のディレクトリを受け入れるか、または [参照] をクリックして別の場所を探します。

8	インストールするパッケージ ファイルに定義済みの Windows NT ユーザーが含まれている場合は、[パッケージ ファイルに保存された NT ユーザーを追加する] チェック ボックスを利用できます。このチェック ボックスをオンにすると、これらのユーザーが新しいパッケージに追加されます。

9	[完了] をクリックします。MTS エクスプローラのウィンドウの右側に新しいパッケージが表示されます。複数のパッケージをインストールする場合は、手順 6 と手順 7 で選択するオプションがすべてのパッケージに適用されます。

Windows NT で既成のパッケージをインストールするには、コンピュータの [インストールされたパッケージ] フォルダを開き、パッケージ ファイルを Windows の エクスプローラから MTS エクスプローラのウィンドウの右側にドラッグする方法もあります。

関連項目

[インストールされたパッケージ] フォルダ


MTS パッケージのアップグレード

MTS パッケージをアップグレードする場合は、まず以前のバージョンを削除し、次に更新されたパッケージをインストールしなければなりません。

パッケージを削除するには

1	MTS エクスプローラのウィンドウの左側で、削除するパッケージが保存されているコンピュータを選択します。

2	選択したコンピュータの [インストールされたパッケージ] フォルダを開いてすべてのパッケージを表示します。

3	削除するパッケージを選択します。

4	次のいずれかの操作を実行します。

•	[動作] メニューの [削除] をクリックします。

•	削除するパッケージをマウスの右ボタンでクリックし、[削除] をクリックします。

•	Del キーを押します。

5	[はい] をクリックしてパッケージを削除します。

パッケージを削除すると、パッケージに含まれているコンポーネントもすべて削除されます。

アップグレードされたパッケージをインストールする方法については、「既成の MTS パッケージのインストール」を参照してください。

関連項目

[インストールされたパッケージ] フォルダ


MTS パッケージ セキュリティを有効にする

MTS は 2 種類のパッケージ セキュリティを提供します。

•	プログラムによるセキュリティ

カスタマイズされたセキュリティをアプリケーションで実現するためのインターフェイスを提供します。プログラムによるセキュリティの使い方の詳細については、『Programmer's Guide』を参照してください。

•	宣言によるセキィリティ

ロールを定義し、MTS エクスプローラを使って Windows NT ユーザーまたはユーザーのグループをロールに割り当てることができます。

重要   ライブラリ パッケージはロールのチェックをサポートしません。セキュリティを有効にするには、アクティブ化の設定をサーバー パッケージに変更しなければなりません。ライブラリ パッケージとサーバー パッケージの詳細については、「MTS アクティブ化のプロパティを設定する」を参照してください。

管理者は、宣言によるセキュリティを使って、アクセス権を持つクライアントだけがパッケージを実行できるようにし、パッケージのセキュリティを確保します。アクセスを許可するには、MTS エクスプローラで MTS ロールと Windows NT のユーザー アカウントおよびグループ アカウントを使います。宣言によるセキュリティは Windows NT アカウントの認証を利用するので、Windows 95/98 コンピュータで実行しているパッケージには宣言によるセキュリティを使うことができません。

宣言によるセキュリティをパッケージに設定するには、次の手順に従って操作します。

1	[新しいロール] ダイアログ ボックスを使って、ロールをパッケージ レベルで定義します。

新しいロールを追加する方法については、「新しい MTS ロールの追加」を参照してください。

2	[ロールにユーザーとグループを追加] ダイアログ ボックスを使って、ユーザーをロールにマップします。ロールに適切なユーザーがマップされていないパッケージは、呼び出すことができません。

ユーザーとグループをロールに追加する方法については、「MTS ロールをユーザーとグループにマップする」を参照してください。

3	特定のコンポーネントまたはインターフェイスへのアクセスを制限する場合は、定義したロールをコンポーネントまたはインターフェイスの [ロール メンバーシップ] フォルダに割り当てます。

4	パッケージの [プロパティ] ダイアログ ボックスの [セキュリティ] タブで、パッケージのセキュリティを有効にします。認証の確認を有効にする方法については、この後の説明を参照してください。

システム パッケージのセキュリティを有効にする前に、現在使用しているユーザー アカウントを Administrator ロールにマップしないと、MTS エクスプローラの (ロールへのユーザーの追加など) 構成変更機能を使用できません。その場合は、Administrator ロールにマップされているユーザーとしてログオンする必要があります。管理者がシステム パッケージへアクセスできなくなることを防止するために、次の場合、MTS エクスプローラのエラー メッセージが表示されます。

•	Administrator ロールにどのユーザーもマップされていないときに、システム パッケージのセキュリティを有効にしようとした場合。

•	システム パッケージのセキュリティが有効になっているときに、Administrator ロールから最後に残ったユーザー アカウントを削除しようとした場合。

注   プライマリ ドメイン コントローラまたはバックアップ ドメイン コントローラとなっているサーバーに MTS がインストールされている場合、MTS エクスプローラでパッケージを管理するには、ユーザーはドメイン管理者でなければなりません。

パッケージのセキュリティを有効にしないと、コンポーネントまたはインターフェイスのロールは MTS によってチェックされません。また、コンポーネントのセキュリティを有効にしないと、コンポーネントのインターフェイスのロールは MTS によってチェックされません。

[ロール メンバーシップ] フォルダにロールを割り当てる方法については、「新しい MTS ロールの追加」を参照してください。

注   パッケージのデバッグ中は、個々のコンポーネントまたはパッケージの宣言によるセキュリティをオフにしておくと便利です。

たとえば、在庫管理を行う Inventory サーバー パッケージへのアクセスを制限する例を考えてみます。システム管理者は、Inventory パッケージへのアクセス権を販売部門のメンバーだけに許可したいと考えています。この場合は、まず Inventory パッケージの [ロール] フォルダを選択します。[動作] メニューの [新規作成] をポイントし、[ロール] をクリックします。次に、新しいロールの名前として「Sales」と入力します。次に、[ユーザー] フォルダを選択します。[動作] メニューの [新規作成] をポイントし、[ユーザー] をクリックします。次に、販売部門の Windows NT グループ アカウント名を入力します。各コンポーネントの [ロール メンバーシップ] フォルダに Sales ロールを追加します。この時点で、販売部門のメンバーだけが Inventory パッケージへのアクセスを許可されます。最後に、そのパッケージを選択し、[プロパティ] ダイアログ ボックスの [セキュリティ] タブで、[認証の確認を実行する] チェック ボックスをオンにしてパッケージの新しいセキュリティの設定を有効にします。

パッケージ内の特定のコンポーネントへのアクセスを制限する場合は、パッケージのコンポーネントどうしがどのようにお互いを呼び出しているかを理解しておかなければなりません。コンポーネントがベース クライアントから直接呼び出される場合、MTS はコンポーネントのロールをチェックします。コンポーネントが同じパッケージ内の別のコンポーネントを呼び出す場合、同じパッケージ内のコンポーネントは相互に "信頼している" ものと見なされるため、MTS はロールをチェックしません。

たとえば、クライアントに (在庫を確認する) CheckInventory コンポーネントの呼び出しを許可するロールを構成し、クライアントが直接 (受注残高を確認する) Backorder コンポーネントを呼び出すことを禁止する例を考えてみます。CheckInventory コンポーネントと Backorder コンポーネントは、両方とも Inventory パッケージ内にあります。この場合は、まず CheckInventory コンポーネントにクライアントの適切なロールを設定しなければなりません。次に、クライアント ID にマップできるロールが Backorder コンポーネントに設定されていないことを確認します。CheckInventory コンポーネントと Backorder コンポーネントはパッケージを共有しているので、CheckInventory コンポーネントが Backorder コンポーネントを呼び出すときに、ロールはチェックされません。

次の条件を満たしている場合、CheckInventory コンポーネントはクライアントの代わりに Backorder コンポーネントを呼び出すことができます。

•	クライアント ID が CheckInventory の適切なロールにマップされている。

•	プログラムによるセキュリティのあらゆる必要条件が満たされている。

このようにして、選択されたコンポーネントへのアクセスを制限しながら、相互に信頼される複数のコンポーネントを含むパッケージを作成することができます。

Backorder コンポーネントを直接呼び出す最初の呼び出し元のロールをチェックするように設定するには、Backorder コンポーネントの [ロール メンバーシップ] フォルダを選択し、[動作] メニューの [新規作成] をポイントします。次に、[ロール] をクリックし、Sales ロールを選びます。これで (ユーザーをマップされた) Sales ロールが Backorder コンポーネントに割り当てられたので、販売部門のメンバーだけが Backorder コンポーネントを実行して在庫切れの商品を確認することができます。新しいセキュリティの設定を有効にするには、Inventory パッケージと Backorder コンポーネントの [認証の確認を実行する] チェック ボックスをオンにします。

ロールのチェックの詳細については、『Programmer's Guide』の「Programmatic Security」を参照してください。

セキュリティ認証を有効にするには

1	システム パッケージの Administrator ロールにまだ自分のユーザー アカウントをマップしていない場合は、マップします。

2	システム パッケージを選択し、[動作] メニューまたはマウスの右ボタンをクリックしたときに表示されるメニューの [プロパティ] をクリックします。

3	[セキュリティ] タブをクリックし、[認証の確認を実行する] チェック ボックスをオンにします。

4	システム パッケージをマウスの右ボタンでクリックし、[シャットダウン] をクリックしてシステム パッケージのサーバー プロセスを停止します。

手順 4 と手順 7 を一度に行って、すべてのサーバー パッケージをシャットダウンすることもできます。すべてのサーバー パッケージをシャットダウンするには、[マイ コンピュータ] アイコンを選択し、[動作] メニューの [サーバー プロセスのシャットダウン] をクリックします。

5	セキュリティを有効にするパッケージを選択し、[動作] メニューまたはマウスの右ボタンをクリックしたときに表示されるメニューの [プロパティ] をクリックします。

6	[セキュリティ] タブをクリックし、[認証の確認を実行する] チェック ボックスをオンにします。

7	セキュリティを有効にするパッケージをマウスの右ボタンでクリックし、[シャットダウン] をクリックしてシステム パッケージのサーバー プロセスを停止します。

配置先のサーバーにパッケージをインストールし、構成したら、コンポーネントの構成が変更されないようにパッケージをロックすることができます。パッケージの構成をロックする方法の詳細については、「MTS パッケージをロックする」を参照してください。

関連項目

System パッケージ、[ロール] フォルダ、[ユーザー] フォルダ、[ロール メンバーシップ] フォルダ、MTS ロールのユーザーを管理する、MTS Overview and Concepts (概要とプログラミングの概念)


MTS パッケージ ID の設定

パッケージ (単一のサーバー プロセス) を次のいずれかのパッケージ ID として実行するように構成できます。

•	対話ユーザー

•	特定の Windows NT ユーザー アカウント

既定の設定では、MTS パッケージは対話ユーザーとして実行されます。

注   パッケージ ID にグループを指定することはできません。

多くの配置環境では、パッケージを Windows NT ユーザー アカウントとして実行することをお勧めします。パッケージが単一の Windows NT ユーザー アカウントとして実行される場合は、パッケージを使用するすべてのクライアントにデータベースへのアクセスを構成する代わりに、そのアカウントだけにデータベースへのアクセスを構成することができます。個々のクライアントにアクセスを許可するのではなく、アカウントにアクセスを許可すると、アプリケーションのスケーラビリティが向上します。

たとえば、SQL Sever データベースの請求情報、販売情報を更新する Accounting パッケージの例を考えてみます。データベースの Accounting テーブルを構成し、Windows NT ユーザーに「読み取り」アクセス権を与えることができます。

パッケージ ID を設定したとき、MTS は入力されたパスワードを確認します。ただし、アカウントのパスワードを変更したときに MTS エクスプローラでパスワードを更新しなかった場合は、パッケージは実行できません。

パッケージ ID を特定のユーザー アカウントに設定するには

1	ID を変更するパッケージを選択します。

2	[動作] メニューの [プロパティ] をクリックし、[ID] タブをクリックします。

3	[このユーザー] を選択し、Windows NT ユーザー アカウントのユーザー名とパスワードを入力します。ユーザー名は、ユーザーのドメイン名と円記号 (\) に続けて入力します。

データベースへのアクセスを制限するためにパッケージ ID を使用する場合は、ユーザー アカウントにデータベースへのアクセス権限を設定しなければなりません。

関連項目

MTS ロールをユーザーとグループにマップする、MTS パッケージ セキュリティを有効にする、新しい MTS ロールの追加、[ID] タブ (パッケージ)


新しい MTS ロールの追加

通常、パッケージの開発時に新しいロールを追加しますが、既存のパッケージに新しいロールを追加しなければならないこともあります。ロールとは、特定の職務に必要な 1 組のシステムレベルの権限です。ロールはパッケージ レベルで設定されます。MTS エクスプローラを使って、作成するロールに Windows NT ユーザーまたはユーザーのグループをマップすることができます。

新しいロールを作成するには

1	MTS エクスプローラのウィンドウの左側で、ロールを組み込むパッケージを選択します。

2	[ロール] フォルダを開きます。

3	次のいずれかの操作を実行します。

•	[動作] メニューの [新規作成] をポイントし、[ロール] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

•	[ロール] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[ロール] をクリックします。

4	表示されるダイアログ ボックスで、新しいロールの名前を入力します。

5	[OK] をクリックします。

警告   有効なユーザーをパッケージのロールにマップしないと、パッケージ セキュリティを有効にすることはできません。

関連項目

MTS ロールをユーザーとグループにマップする、MTS パッケージ セキュリティを有効にする、MTS パッケージ ID の設定、[ロール] フォルダ、MTS ロールのユーザーを管理する


MTS ロールをユーザーとグループにマップする

アプリケーションをインストールし、配置するときは、すべての既存のロールに Windows NT ユーザーとグループを割り当てなければなりません。ロールは、コンポーネントとインターフェイスへのユーザーのアクセスを定義します。

ユーザーをロールに割り当てるには

1	MTS エクスプローラのウィンドウの左側で、ロールを割り当てるコンポーネントが含まれるパッケージを選択します。

2	[ロール] フォルダを開きます。

3	ユーザーを割り当てるロールをダブルクリックします。

4	[ユーザー] フォルダを開きます。

5	次のいずれかの操作を実行します。

•	[動作] メニューの [新規作成] をポイントし、[ユーザー] をクリックします。

•	MTS ツール バーの [新しいオブジェクトの作成] ボタンをクリックします。

•	[ユーザー] フォルダをマウスの右ボタンでクリックし、[新規作成] をポイントします。次に、[ユーザー] をクリックします。

6	表示されるダイアログ ボックスで、ユーザー名またはグループをロールに追加します。[ユーザーの表示] ボタンおよび [検索] ボタンを使って、ユーザー アカウントを探すことができます。

7	[OK] をクリックします。

注  Windows 95/98 コンピュータでユーザーをロールに割り当てるには、Windows 95/98 コンピュータにユーザー レベルのアクセス管理を設定する必要があります。Windows 95/98 コントロール パネルを開いて [ネットワーク] をクリックします。[アクセス権の管理] タブをクリックして [ユーザー レベルのアクセス管理] を選択します。この設定の詳細については、Windows 95/98 のマニュアルを参照してください。

関連項目

新しい MTS ロールの追加、MTS パッケージ セキュリティを有効にする、MTS パッケージ ID の設定、[ロール] フォルダ、[ユーザー] フォルダ、MTS ロールのユーザーを管理する


MTS パッケージの保守

パッケージの作成、配布、配置に成功したら、管理者は MTS エクスプローラを使って MTS パッケージを保守することができます。MTS パッケージの保守には、パッケージとパッケージのコンポーネントの状態およびプロパティを監視すること、必要に応じてパッケージとパッケージのコンポーネントのプロパティを再構成することが含まれます。

ここでは、次のトピックについて説明します。

MTS エクスプローラを使って状態とプロパティを監視する

MTS エクスプローラの [プロパティ] ダイアログ ボックスを使う

MTS ロールのユーザーを管理する

MTS のレプリケーションを使う


MTS エクスプローラを使って状態とプロパティを監視する

MTS エクスプローラの状態表示とプロパティ表示を使って、アクティブなパッケージとそのコンポーネントの状態およびプロパティを監視できます。MTS エクスプローラでアイテムを選択し、MTS エクスプローラ ツール バーの [状態表示] ボタンまたは [プロパティ表示] ボタンをクリックすると、アイテムの状態やプロパティを表示できます。

状態表示を使うと、コンピュータ、パッケージ、およびコンポーネントの状態を MTS エクスプローラで表示することができます。たとえば、[コンピュータ] フォルダの状態表示では、Microsoft 分散トランザクション コーディネータ (MS DTC) が起動されているかどうかを示し、[インストールされたパッケージ] フォルダの状態表示では、どのパッケージが実行されているかを示します。パッケージ内のコンポーネントの状態表示では、コンポーネントのプログラム ID (progID)、アクティブ化されているオブジェクト、および呼び出されているオブジェクトを示します。状態表示を使って、管理するコンピュータとアプリケーション プロセスの状態をすばやく表示することができます。

MTS エクスプローラで状態表示を使うには

1	[コンピュータ] フォルダ、[インストールされたパッケージ] フォルダ、または [コンポーネント] フォルダを選択します。

2	MTS ツール バーの [状態表示] ボタンをクリックします。

注   状態表示では、ユーティリティおよびシステム パッケージの状態は表示されません。

パッケージとコンポーネントのプロパティに関する情報をすばやく収集するには、プロパティ表示を使います。たとえば、コンポーネントのプロパティ表示では、コンポーネントのプログラム ID (ProgID)、トランザクションの設定、ダイナミック リンク ライブラリ (DLL) の場所、クラス ID (CLSID)、スレッド モデル、およびセキュリティ認証の設定が表示されます。また、プロパティ表示を使って、パッケージ内のすべてのコンポーネントのトランザクション プロパティをすばやく表示することができます。

MTS エクスプローラでプロパティ表示を使うには

1	MTS エクスプローラのウィンドウの左側で、[インストールされたパッケージ] フォルダや [コンポーネント] フォルダなど、状態を表示するフォルダを選択します。

2	MTS エクスプローラ ツール バーの [プロパティ表示] ボタンをクリックします。選択したフォルダ内のアイテムの状態が、MTS エクスプローラのウィンドウの右側の列に表示されます。

関連項目

MTS エクスプローラの [プロパティ] ダイアログ ボックスを使う


MTS エクスプローラの [プロパティ] ダイアログ ボックスを使う

パッケージとコンポーネントの[プロパティ] ダイアログ ボックスでは、MTS パッケージの構成を変更できます。たとえば、コンポーネントのトランザクション プロパティを変更する場合は、コンポーネントの [プロパティ] ダイアログ ボックスでトランザクションの設定を変更することができます。特定のプロパティの設定を再構成する前に、「MTS パッケージの作成」と 「MTS パッケージのインストール」を参照して、MTS エクスプローラでさまざまなプロパティを設定することの意味と手順を確認してください。

パッケージとそのコンポーネントの変更や削除を防止するために、パッケージをロックすることができます。インストール時または配置時にパッケージがロックされている場合は、コンポーネントのプロパティを変更する前に、パッケージのロックを解除する必要があります。ロックの詳細については、「MTS パッケージをロックする」を参照してください。

[プロパティ] ダイアログ ボックスを使って、パッケージとアプリケーションのプロパティを構成するには

1	次のいずれかの方法で、[プロパティ] ダイアログ ボックスを表示します。

•	プロパティを設定するアイテムをマウスの右ボタンでクリックし、[プロパティ] をクリックします。

•	MTS エクスプローラのウィンドウの左側で目的のアイテムを選択し、[動作] メニューの [プロパティ] をクリックします。

2	[プロパティ] ダイアログ ボックスで、適切なプロパティを変更し、[OK] または [適用] をクリックします。

3	[マイ コンピュータ] アイコンを選択し、[動作] メニューの [すべてのコンポーネントの更新] をクリックして [マイ コンピュータ] のすべてのコンポーネントを更新します。または、MTS エクスプローラのウィンドウの右側で、[インストールされたパッケージ] フォルダのパッケージを選択し、MTS ツール バーの [最新の情報に更新] ボタンをクリックして個々のパッケージを更新します。

注   パッケージのアクティブ化レベルを変更した場合、変更を有効にするには、そのパッケージのプロセスをシャットダウンする必要があります。パッケージ プロセスをシャットダウンするには、変更したパッケージをマウスの右ボタンでクリックし、[シャットダウン] をクリックします。MTS 1.x コンピュータ上のリモートで管理されているパッケージは、個別にシャットダウンすることはできません。

関連項目

MTS エクスプローラを使って状態とプロパティを監視する


MTS ロールのユーザーを管理する

管理者は、次の操作を実行してロールにマップした Windows NT ユーザーとユーザーのグループを管理する必要があります。

•	ロールに新しいユーザーやグループを追加する。

•	ロールからユーザーやグループを削除する。

•	あるロールから別のロールへユーザーやグループを移動する。

サーバー パッケージのクライアントの増加に合わせて、MTS エクスプローラを使って新しいユーザーをパッケージのロールにマップします。新しいユーザーをロールにマップする方法の詳細については、「MTS ロールをユーザーとグループにマップする」を参照してください。

ロールからユーザーを削除したり、既存のロールから新しく作成したロールへユーザーまたはグループを移動する必要がある場合があります。たとえば、従業員が会社を辞めた場合は、辞めた従業員に関連付けられていたロールからそのユーザーを削除します。

既存のパッケージの新しいロールを作成するときに、あるロールから別のロールへユーザーまたはグループを移動する必要がある場合があります。たとえば、Accounting パッケージの Clerk ロールを作成する場合は、Accounting データの読み取り権限と書き込み権限を持つ既存の Manager ロールから、読み取り権限だけを持つ Clerk ロールに一部のユーザーまたはユーザーのグループを移動する必要があるかもしれません。ユーザーまたはユーザーのグループを移動するには、ロールからユーザーまたはユーザーのグループを削除し、削除したユーザーを新しいロールにマップしなければなりません。

ユーザーをロールから削除するには

1	グループまたはユーザーを削除するロールが含まれているパッケージを探します。MTS エクスプローラのウィンドウの左側で、そのパッケージを選択します。

2	[ロール] フォルダを開きます。

3	削除するユーザーが定義されているロールをダブルクリックします。

4	[ユーザー] フォルダを開きます。

5	削除するユーザーを選択します。

6	次のいずれかの操作を実行します。

•	[動作] メニューの [削除] をクリックします。

•	削除するユーザーをマウスの右ボタンでクリックし、[削除] をクリックします。

•	Del キーを押します。

7	表示されるダイアログ ボックスで [はい] をクリックします。

関連項目

[ロール] フォルダ、[ユーザー] フォルダ、MTS パッケージ セキュリティを有効にする、MTS パッケージ ID の設定、新しい MTS ロールの追加、MTS ロールをユーザーとグループにマップする


MTS のレプリケーションを使う

MTS には、Microsoft Cluster Server (MSCS) と組み合わせて使用できるレプリケーション機能が用意されています。クラスタ内の MTS サーバーが故障したり、オフラインになったりした場合は、もう一方のサーバーが故障したサーバーの動作を引き継ぎます。

MTS サーバーをレプリケートする方法

 MTS サーバーをレプリケートするには

1	MTS をクラスタの両方のコンピュータにインストールします。詳細については、「MTS を Microsoft Cluster Server と組み合わせて使うように構成する」を参照してください。

2	マスタ コンピュータを指定し、そのコンピュータにパッケージをインストールします。

3	インポートされたすべてのコンポーネントを両方のコンピュータに登録します。

4	ランタイム ライブラリなどの依存ファイルが両方のコンピュータにインストールされていることを確認します (この後の「制限事項」を参照してください)。

5	[マイ コンピュータのプロパティ] ダイアログ ボックスの [オプション] タブで、[レプリケーションの共有ディレクトリ] ボックスにマスタのレプリケーションの共有ディレクトリ名を指定します (この後の「パッケージの内容のレプリケーション」を参照してください)。

6	MTXREPL.EXE コマンドライン ユーティリティを実行します。

MTS サーバーをレプリケートするには、MTXREPL.EXE コマンドライン ユーティリティを使います。マスタとレプリケート先の両方のコンピュータを実行していなければなりません。MTXREPL.EXE では次の引数を指定します。

MTXREPL.EXE <マスタ> <レプリケート先>

MTS のレプリケーションでは、単一マスタ方式を使用し、MTS カタログ情報を １ 台のマスタ コンピュータから 1 台のレプリケート先コンピュータへコピーします。別のレプリケート先コンピュータにレプリケートするには、MTXREPL.EXE ユーティリティをもう一度実行します。単一マスタ方式は厳密に行われるわけではないので、レプリケート先コンピュータを別の MTS サーバー アプリケーションのマスタとして使うこともできます。

この後の「MTS のレプリケーションでは行われないこと」に記述されている場合を除いて、レプリケーションを行うと、MTS はレプリケート先のカタログをレプリケート元のカタログに "完全に" 置き換えます。部分的なレプリケーションはできません。MTS のレプリケーションが失敗した場合は、MTXREPL.EXE ユーティリティをもう一度実行します。

管理者には、MTS のレプリケーションを行う責任があり、マスタ サーバーのパッケージに加えられた変更がクラスタ内のすべてのコンピュータにレプリケートされていることを確認しなければなりません。

レプリケート先コンピュータで MTS コンポーネントが実行されていないときにレプリケーションを行うことをお勧めします。MTS の起動時には、カタログ情報が読み込まれている間に失敗を知らせるウィンドウが表示されることがあります。この時間帯にレプリケーションが行われると、パッケージの起動は失敗し、クライアントは再試行を要求されます。

IIS パッケージのレプリケーション

IIS パッケージをレプリケートするには、Microsoft Internet Information Server (IIS) Version 4.0 のレプリケーション ユーティリティを使用します。IIS のレプリケーションでは、すべての MTS カタログ情報が自動的にコピーされます。このため、MTS レプリケーション ユーティリティを実行する必要はありません。実際に、IIS 4.0 がインストールされている場合、MTS レプリケーション ユーティリティは動作しません。

パッケージの内容のレプリケーション

MTS のレプリケーションでは、すべての必要なコンポーネント (ダイナミック リンク ライブラリ (DLL)、タイプ ライブラリ、およびプロキシ/スタブ DLL) がコピーされます。レプリケート先コンピュータがこれらのファイルにアクセスできるようにするには、[マイ コンピュータのプロパティ] ダイアログ ボックスの [オプション] タブで、[レプリケーションの共有ディレクトリ] ボックスにマスタのレプリケーションを共有するためのディレクトリ名を指定しなければなりません。この共有をマスタ上に作成し、レプリケート先コンピュータに読み取り権限を許可しなければなりません。[レプリケーションの共有ディレクトリ] ボックスに指定する名前は共有名であり、共有名がマップされるディレクトリではありません。たとえば、d:\mtx\repl を MyReplPoint として共有する場合は、[レプリケーションの共有ディレクトリ] ボックスに d:\mtx\repl ではなく MyReplPoint を指定します。

レプリケーションの共有ディレクトリは、レプリケート先コンピュータのシステム パッケージ ID に読み取り権限を許可しなければなりません。レプリケート先のシステム パッケージがロールのチェックを行う場合、マスタのシステム パッケージ ID はレプリケート先のシステム パッケージの Administrator ロールに属していなければなりません。

レプリケート先コンピュータでファイルがインストールされる場所は、パッケージ内の最初のコンポーネント DLL の場所によって決まります。このコンポーネントが既定のパッケージ ディレクトリの下のサブディレクトリにある場合は、そのサブディレクトリがレプリケート先コンピュータにそのままコピーされます。既定のパッケージ ディレクトリは、MTS のセットアップ時に設定されます。たとえば、MTS を c:\Program Files\Mts にインストールすると、既定のパッケージ インストール先ディレクトリは c:\Program Files\Mts\Packages になります。

パッケージがこのディレクトリの下にインストールされている場合、それらのパッケージは、レプリケート先コンピュータの既定のパッケージ インストール先ディレクトリを基準にして同じ場所にコピーされます。たとえば、次の表のようになります。

コンピュータ	既定のパッケージ ディレクトリ	パッケージ インストール先ディレクトリ
マスタ	c:\Program Files\Mts\Packages	c:\Program Files\Mts\Packages\MyPak
レプリケート先	d:\Mts\Packages	d:\Mts\Packages\MyPak
既定のパッケージ インストール先ディレクトリ以外の場所にインストールされたパッケージは、レプリケート先コンピュータの "外部の" サブディレクトリにインストールされます。たとえば、次の表のようになります。

コンピュータ	パッケージ インストール先ディレクトリ
マスタ	パッケージ A は c:\Program Files\Mts\Packages\MyPak パッケージ B は d:\misc
レプリケート先	パッケージ A、B 共に d:\Mts\Packages\MyPak
既定のパッケージ ディレクトリの下にパッケージをインストールすることをお勧めします。また、同じパッケージのファイルをすべて同じディレクトリに置くことをお勧めします。

MTS サーバー クラスタの管理

管理者は、MSCS クラスタを管理するときは、常に物理コンピュータ名を使わなければなりません。MSCS クラスタのマスタ コンピュータ上でレプリケート先を表示する場合は、レプリケート先の物理コンピュータ名を使います。マスタとレプリケート先との間でレプリケーションを行うときは、物理コンピュータ名を使います。

MSCS クラスタに MTS アプリケーションを配置するときは、[マイ コンピュータのプロパティ] ダイアログ ボックスの [オプション] タブの [リモート サーバー名] ボックスに、仮想サーバー名を指定しなければなりません。アプリケーション実行可能ファイル ユーティリティを使ってパッケージをエクスポートすると、アプリケーションをインストールするクライアントは、仮想サーバーにアクセスするように設定されます。[リモート サーバー名] ボックスに仮想サーバー名を指定しないと、クライアントは物理コンピュータにアクセスするように設定されますが、これはフェールオーバーによる保護を行うための構成として不適切です。

異なる仮想サーバー名を指定すると、フェールオーバーによる保護と共に静的な負荷のバランスをとることができます。各物理コンピュータに 1 つずつ、合計 2 つの仮想サーバー名を指定することにより、両方のコンピュータにインストールされたパッケージのクライアント インストール実行可能ファイルを作成することができます。パッケージの配布をレプリケーションのクライアント間で分担することにより、静的な負荷のバランスをとることができます。

 仮想サーバーを使って MTS アプリケーションの負荷のバランスをとるには

1	負荷のバランスをとる方法を決めます。たとえば、次のような方法があります。

•	すべてのパッケージを一度に 1 台のコンピュータだけで実行する方法。

•	すべてのパッケージを両方のコンピュータで実行する方法。

•	一部のパッケージを一方のコンピュータで、そのほかのパッケージをもう一方のコンピュータで実行する方法。

2	MSCS クラスタ アドミニストレータを使って、両方のコンピュータの仮想サーバー名を作成します。

3	手順 2 で作成した仮想サーバー名を使って、パッケージをエクスポートします。

•	すべてのパッケージを一度に 1 台のコンピュータだけで実行する場合は、1 つの仮想サーバー名を使ってすべてのパッケージをエクスポートします。

•	すべてのパッケージを同時に両方のコンピュータで実行する場合は、すべてのパッケージをそれぞれの仮想サーバー名を使って 1 回ずつ、合計 2 回エクスポートします。次に、2 つの異なるクライアント インストール実行可能ファイルのセットをクライアントに配布しなければなりません。

•	パッケージの半分を一方のコンピュータで、残りの半分をもう一方のコンピュータで実行する場合は、それぞれの仮想サーバー名を使ってパッケージを半分ずつエクスポートします。

4	クライアント コンピュータでクライアント実行可能ファイルを実行します。手順 1 で指定した負荷のバランスをとる方法に応じて、各クライアントで数個の実行可能ファイルが実行されます。

MTS のレプリケーションでは行われないこと

MTS のレプリケーションでは次の作業は行われません。

•	MTS のインストール。MTS アプリケーションを実行する前に、各レプリケート先コンピュータに MTS をセットアップしなければなりません。

•	MTS システム パッケージ、MTS ユーティリティ パッケージ、および IIS ユーティリティ パッケージの置き換え。これらのパッケージは、マスタとレプリケート先でまったく同じように構成しなければなりません (ファイル パスは異なることがあります)。MTS はこの作業を行わないので、管理者が必要に応じてパッケージの両方のセットを同期化しなければなりません。

•	レプリケーションの共有ディレクトリやリモート サーバー名のプロパティなど、コンピュータ固有の情報のレプリケーション。

•	ランタイム ライブラリなど、MTS が検出できない MTS コンポーネントの依存ファイルのレプリケーション。アプリケーションを正しく実行するには、これらのファイルを各レプリケート先コンピュータにコピーしなければなりません。

•	ローカル コンピュータのセキュリティ アカウントのレプリケーション。このようなアカウントをクラスタ内でロールやパッケージ ID に使用することはお勧めできません。

•	アプリケーションが依存する持続的なデータのレプリケーション。たとえば、SQL Server は SQL Server データベースを自動的にフェールオーバーしますが、管理者は、データベースのフェールオーバーがアプリケーションに適用されるように構成されていることを確認しなければなりません。

制限事項

•	Windows 95/98 コンピュータからの MTS のレプリケーション、または Windows 95/98 コンピュータへの MTS のレプリケーションはサポートしていません。

•	レプリケート先コンピュータで実行するように設定されているリモート コンポーネントがマスタ上にあると、MTS のレプリケーションは失敗します。

•	インポートされたコンポーネントは、レプリケート先コンピュータに既に登録されている場合だけレプリケートすることができます。インストールされたコンポーネントは、レプリケーション ユーティリティによってレプリケート先で自動的に登録され、構成されます。マスタにインポートされたコンポーネントをレプリケートする場合、レプリケーション ユーティリティは、レプリケート先に既に登録されているコンポーネントを検出しようとします。レプリケーション ユーティリティを実行する前に、インポートされたコンポーネントを各レプリケート先コンピュータに手動で登録しなければなりません。

•	MTS 2.0 よりも前のバージョンの MTS からのレプリケーション、または MTS 2.0 よりも前のバージョンの MTS へのレプリケーションはサポートしていません。

関連項目

MTS を Microsoft Cluster Server と組み合わせて使うように構成する、[オプション] タブ (コンピュータ)


MTS トランザクションの管理

分散トランザクションの動作を理解すると、Microsoft Transaction Server (MTS) パッケージのトランザクションを効率よく管理するために役立ちます。ここでは、トランザクションの動作、および MTS エクスプローラでトランザクションを監視し、管理する方法について説明します。

ここでは、次のトピックについて説明します。

MTS トランザクションについて

MS DTC の管理

MTS トランザクションの監視

Windows 95/98 で MTS トランザクションの監視

MTS トランザクションの状態について

MTS トランザクションの解決

関連項目

[トランザクションの一覧] ウィンドウ、[トランザクションの統計] ウィンドウ、トランザクション アイコン、[トレース メッセージ] ウィンドウ


MTS トランザクションについて

Microsoft Transaction Server (MTS) を使うと、アプリケーション内で分散トランザクションを簡単に使用、監視、および管理することができます。分散トランザクションとは、複数のシステム上でトランザクションに保護されたリソースを更新する必要があるトランザクションです。MTS トランザクション マネージャである Microsoft 分散トランザクション コーディネータ (MS DTC) は、Windows NTｮ システムと Windowsｮ 95/98 システムで分散トランザクションを扱う機能を提供しています。

MS DTC を使うと、1 つのシステム上でトランザクションに保護された複数のリソースを更新することもできます。たとえば、MS DTC を使うと、Microsoft SQL Server データベース、Microsoft Message Queue Server メッセージ キュー、および Oracle データベースを １ つのトランザクションの元で更新することができます。

関連項目

MS DTC の管理、MTS トランザクションの監視、Windows 95/98 で MTS トランザクションの監視、MTS トランザクションの状態について、MTS トランザクションの解決


MS DTC の管理

トランザクションを管理するには、まず、Microsoftｮ 分散トランザクション コーディネータ (MS DTC) を開始しなければなりません。MS DTC を開始すると、次のことが可能になります。

•	MTS は、トランザクション コンポーネントの代わりにトランザクションを初期化できます。

•	MTS トランザクション コンポーネントは、ほかのネットワーク システムで初期化されたトランザクションに参加できます。

•	あるサーバーの Microsoft SQL Server および Microsoft Message Queue Server (MSMQ) は、ほかのサーバーの MTS コンポーネントと共にトランザクションに参加できます。

管理者が MTS サーバー上で MS DTC を開始しなかった場合、クライアントは管理者が管理しているトランザクション パッケージにアクセスすることはできますが、サーバー コンポーネントはトランザクションに参加できません。

注:  MS DTC をクライアントとしてインストールしているユーザーが、Windows NT コンピュータ上で MS DTC クライアントを設定し、実行するには、ローカル レジストリへの書き込みアクセスとサーバーの Software\Classes キーへのリモート読み取りアクセスが許可されていなければなりません。

MS DTC は、MTS エクスプローラまたは (MTS をインストールしていない場合は) Windows NT のコントロール パネルを使用して開始できます。

MTS エクスプローラを使って MS DTC を開始または停止するには

1	MTS エクスプローラのウィンドウの左側で、トランザクション パッケージを管理しているコンピュータを選択します。

2	[動作] メニューの [MS DTC 開始] または [MS DTC 停止] をクリックします。または、目的のコンピュータをマウスの右ボタンでクリックし、[MS DTC 開始] または [MS DTC 停止] をクリックします。

コンピュータの [プロパティ] ダイアログ ボックスの [詳細設定] タブを使って、DTC ログ ファイルの場所とサイズなど、DTC の設定を構成することもできます。

Windows NT のコントロール パネルを使って MS DTC を開始または停止するには

1	[スタート] ボタンをクリックし、[設定] をポイントします。次に、[コントロール パネル] をクリックします。

2	[サービス] アイコンをクリックします。

3	[サービス] の一覧で [MSDTC] を選択し、[開始] をクリックします。

4	[閉じる] をクリックして [サービス] ウィンドウを閉じます。

既定の設定では、Microsoft 分散トランザクション コーディネータ (MS DTC) は、Windows NT システムまたは Windows 95/98 システムの起動時に自動的に開始するように構成されます。Windows 95/98 コンピュータの再起動後に MS DTC が自動的に開始されないようにするには、レジストリ エディタを使用して "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunServices" レジストリ キーを探し、MSDTC という名前の値エントリを削除します。Windows NT コンピュータの再起動後に MS DTC が自動的に開始されないようにするには、コントロール パネルの [サービス] アイコンをクリックします。次に、一覧の "MSDTC" を選択して [スタートアップ] をクリックします。[スタートアップの種類] の [手動] を選択して [OK] をクリックします。

Windows 95/98 コンピュータの再起動後に MS DTC が自動的に開始されるようにするには、レジストリ エディタを使用して "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\RunServices" レジストリ キーの下に、文字列値 "msdtcw -start" を持つ MSDTC という名前のエントリを作成します。Windows NT コンピュータでは、コントロール パネルの [サービス] オプションを使って、MS DTC を自動的に開始するように設定できます。

重要:  MTS トランザクション コンポーネント、SQL Server、または MSMQ を実行するコンピュータでは、MS DTC を自動的に開始するように設定することを強く推奨します。

クラスタ サーバーでの MS DTC の開始と停止

クラスタ サーバーでは、MTS エクスプローラまたは MSCS 管理ユーティリティを使って MS DTC を開始または停止することができます。"net start msdtc" および "net stop msdtc" コマンドは、使用できません。MSCS クラスタ上でコマンド プロンプトから MS DTC を開始または停止するには、"msdtc -start" および "msdtc -stop"を使用します。

MS DTC の設定を構成するには

1	MTS エクスプローラのウィンドウの右側で、トランザクション パッケージを管理しているコンピュータを選択します。

2	[動作] メニューの [プロパティ] をクリックします。または、目的のコンピュータをマウスの右ボタンでクリックし、[プロパティ] をクリックします。

3	[詳細設定] タブを選択します。[トランザクションの一覧] ウィンドウと [トレース メッセージ］ ウィンドウにトランザクションがどのように表示されるかを調整することができます。MS DTC ログの場所とサイズを変更することもできます。MS DTC ログのサイズを大きくすると、同時により多くのトランザクションを実行することができます。

重要   MS DTC のログ ファイルのサイズには上限があります。

•	Windows NT では、ログ サイズの上限は 512MB です。

•	Windows 95/98 では、ログ サイズの上限は 64MB です。

MS DTC ログ ファイル

MS DTC ログ ファイルは、圧縮されたディレクトリに置くことができます。ただし、最適なパフォーマンスを得るには、MS DTC ログ ファイルを圧縮したり、圧縮されたディレクトリには置かないでください。MS DTC は、ログ ファイルを使用する前に圧縮を解除する必要があります。

DTCXATM.LOG ファイルの削除

インストールされた MTS 2.0 を更新するときは、更新する前に DTCXATM.LOG ファイルを削除します。DTCXATM.LOG を削除する前に、MS DTC サービスを停止してください。

リモートの MS DTC コンピュータ間のセキュリティと通信

アプリケーションが 2 つ以上のコンピュータにわたってトランザクションを処理する場合、これらのコンピュータ上の MS DTC を相互に通信できるように構成する必要があります。既定の設定では、MS DTC はシステム アカウント ID の元で実行されます。2 つのコンピュータの Guest アカウントが利用できる場合のみ、一方のコンピュータ上の MS DTC は、もう一方のコンピュータ上の MS DTC と通信できます。いずれかのコンピュータまたはそれらのコンピュータが属す Windows NT ドメインで Guest アカウントが利用できない場合は、リモート コンピュータと通信できるほかのユーザー名の元で MS DTC を構成する必要があります。

注  Microsoft Cluster Server (MSCS) 環境で MS DTC を使う場合は、Windows NT QFE をインストールしなければなりません。この QFE は、クラスタ サーバー上の MS DTC へ接続を試みたときに、MS DTC クライアントをハングさせる可能性があるリモート プロシージャ コール (RPC) の問題を解決します。http://www.microsoft.com/japan/products/ntupdate/nt4sp3/j041091.htm からインストールすることができます。

関連項目

MTS トランザクションについて、MTS トランザクションの監視、Windows 95/98 で MTS トランザクションの監視、[詳細設定] タブ (コンピュータ)、[トランザクションの一覧] ウィンドウ、[トランザクションの統計] ウィンドウ、トランザクション アイコン、[トレース メッセージ] ウィンドウ


MTS トランザクションの監視

MTS エクスプローラのトランザクション関連のウィンドウを使って、MTS アプリケーション内のトランザクションを管理することができます。[トレース メッセージ] ウィンドウ、[トランザクションの統計] ウィンドウ、および [トランザクションの一覧] ウィンドウでは、Microsoft 分散トランザクション コーディネータ (MS DTC) が管理するトランザクションの状態に関する重要な情報を提供します。

注  トランザクションが既定のタイムアウト値の 60秒以内に終了しない場合は、トランザクションは自動的にアボートされます。トランザクション タイムアウトは、[マイ コンンピュータ] の [プロパティ] の [オプション] タブで変更できます。

[トランザクションの一覧] ウィンドウを使って、トランザクションの状態を解決することができます。詳細については、「MTS トランザクションの解決」を参照してください。

[トランザクションの一覧] ウィンドウを使って、トランザクションを監視するには

1	MTS エクスプローラのウィンドウの左側で、トランザクションのホストになっているコンピュータを選択します。

2	[トランザクションの一覧] アイコンをダブルクリックします。

3	ウィンドウの右側の任意の場所をマウスの右ボタンでクリックし、[表示] をポイントします。

4	次のいずれかのコマンドをクリックします。

•	[大きいアイコン]

トランザクションが大きいアイコンで表示されます。

•	[小さいアイコン]

トランザクションが小さいアイコンで表示されます。

•	[詳細]

1 列にトランザクションの一覧が表示され、別の 1 列に各トランザクションに関連付けられている作業 ID ユニットが表示されます。この ID は、トランザクションの開始時に MS DTC が生成する、トランザクションのグローバルに一意の ID です。親トランザクションと従属トランザクションの一覧も表示されます。

•	[一覧]

1 列にトランザクションが順番に表示されます。

注   [小さいアイコン] コマンドと [一覧] コマンドを使うと、一度に最も多くのトランザクションが表示されます。[詳細] コマンドを使うと、トランザクション情報が最も詳しく表示され、[大きいアイコン] コマンドを使うと、トランザクションが最も見やすい形式で表示されます。

トランザクション統計情報を表示するには

1	MTS エクスプローラのウィンドウの左側で、トランザクション統計情報を表示するコンピュータを選択します。

2	[トランザクションの統計] アイコンをダブルクリックします。

トレース メッセージを表示するには

1	MTS エクスプローラのウィンドウの左側で、トランザクションのホストになっているコンピュータを選択します。

2	[トレース メッセージ] アイコンをダブルクリックします。

[トランザクションの統計] ウィンドウは、MTS エクスプローラのウィンドウの右側に表示されます。

トランザクションのプロパティ

トランザクションのプロパティを表示するには、選択されたトランザクションをマウスの右ボタンでクリックし、[プロパティ] をクリックします。[プロパティ] コマンドを使うと、トランザクションに関係しているすべてのトランザクション マネージャの一覧が表示されます。子トランザクションをマウスの右ボタンでクリックし、[プロパティ] をクリックすると、そのトランザクションの直接の親トランザクションの一覧が表示されます。選択したトランザクションが親トランザクションの場合は、そのトランザクションの直接の子トランザクションの一覧が表示されます。

関連項目

MTS トランザクションについて、Windows 95/98 で MTS トランザクションの監視、MTS トランザクションの状態について、MTS トランザクションの解決、[トランザクションの一覧] ウィンドウ、[トランザクションの統計] ウィンドウ、トランザクション アイコン、[トレース メッセージ] ウィンドウ


Windows 95/98 で MTS トランザクションの監視

MTS エクスプローラの次のウィンドウを使って、Windows 95ｮ、Windows 98ｮ コンピュータ上または Windows NT コンピュータ上の MTS トランザクションを管理することができます。

•	[トランザクションの統計]

•	[トランザクションの一覧]

•	[トレース メッセージ]

既定の設定では、Microsoft 分散トランザクション コーディネータ (MS DTC)asdefDTC は、Windows NT システムまたは Windows 95/98 システムの起動時に自動的に開始するように構成されます。Windows 95/98 コンピュータの再起動時に MS DTC が自動的に開始しないようにするには、レジストリ エディタを使って、HKEY_LOCAL_MACHINE･Software･Microsoft･Windows･CurrentVersion･RunServices レジストリ キーを探し、MSDTC という名前の値エントリを削除します。MS DTC の自動スタートアップをもう一度有効にするには、レジストリ エディタを使って、文字列値 msdtcw -start を持つ MSDTC という名前の値エントリを HKEY_LOCAL_MACHINE･Software･Microsoft･Windows･CurrentVersion･RunServices レジストリ キーの下に作成します。

注   Windows NT コンピュータ上で MS DTC クライアントを構成し、実行するには、ユーザーはローカル レジストリへの書き込みアクセスとサーバーの Software\Classes キーへのリモート読み取りアクセスを許可されていなければなりません。

Windows 95/98 コンピュータから Windows NT コンピュータをリモートで管理する場合は、リモート レジストリ サービスをインストールしなければなりません。リモート レジストリ サービスを使うと、(適切なアクセス権があれば) リモートの Windows NT コンピュータのレジストリ エントリを変更できます。リモート レジストリ サービスは、Windows 95/98 の CD-ROM の \Admin\Nettols\Remotreg ディレクトリにあります。リモート レジストリ サービスのインストール手順については、Regserv.txt ファイルを参照してください。

Windows 95/98 にはイベント ログがないので、MS DTC のイベントは msdtc.txt というテキスト ファイルに保存されます。msdtc.txt ファイルは、Windows ディレクトリの \MTSLogs サブディレクトリにあり、MS DTC のイベントに関する情報を保存します。

Windows 95/98 で MS DTC ログ ファイルを再設定する場合、"MTxOCI" と表示するダイアログ ボックスの後に、"MS DTC ログ ファイルの作成に失敗しました。" と表示するダイアログ ボックスが現れる場合があります。この問題が発生した場合、コンピュータの再起動時に MS DTC を自動的に開始しないように設定する必要があります。設定が終わったら、コンピュータを再起動して、ログ ファイルをリセットします。これによって、MS DTC を自動的に開始するように再設定できるようになります。

MS DTC ログ ファイルの再設定時に起こるそのほかの問題は、MTS エクスプローラを閉じてから MTS エクスプローラを再開し、再度設定を行うことで解決できます。場合によっては、MS DTC ログ ファイルの問題が解決するまで、MTS エクスプローラをシャットダウンして再開することを何度か繰り返す必要があります。

関連項目

MTS トランザクションについて、MTS トランザクションの監視、[トランザクションの一覧] ウィンドウ、[トランザクションの統計] ウィンドウ、トランザクション アイコン、[トレース メッセージ] ウィンドウ


MTS トランザクションの状態について

トランザクションを管理するには、さまざまなトランザクションの状態と、管理している MTS パッケージにトランザクションの状態が及ぼす影響について理解しなければなりません。トランザクションの状態は、Microsoft 分散トランザクション コーディネータ (MS DTC) の [トランザクションの一覧] ウィンドウの [大きいアイコン] 形式で表示される次のアイコンによって表されます。

アイコン	説明
	アクティブ トランザクションが開始されました。
	アボート中 トランザクションをアボートしています。MS DTC は、すべての関連部分に、トランザクションをアボートしなければならないことを通知しています。 この時点でトランザクションの結果を変更することはできません。
	アボート トランザクションがアボートされました。すべての関連部分は、通知を受けました。アボートされたトランザクションは、[トランザクションの一覧] ウィンドウのトランザクションの一覧からすぐに削除されます。 この時点でトランザクションの結果を変更することはできません。
	準備中 クライアント アプリケーションがコミット要求を発行しました。MS DTC は、すべての関連部分から準備完了の応答を集めています。
	準備完了 すべての関連部分が準備完了の応答を返しました。
	イン ダウト トランザクションが別の MS DTC によって準備され、調整されており、その調整役の MS DTC がアクセスできなくなっています。システム管理者は、[トランザクションの一覧] ウィンドウ内でマウスの右ボタンをクリックし、[解決] をポイントします。次に、[コミット] または [アボート] をクリックすると、強制的にトランザクションをコミットまたはアボートさせることができます。強制的に処理を行うと、そのトランザクションは [強制コミット] または [強制アボート] として表示されます。 警告   イン ダウトのトランザクションを手動で強制的に処理する前に、必ず「MTS トランザクションの解決」をお読みください。
	強制コミット 管理者が、イン ダウトのトランザクションを強制的にコミットしました (「MTS トランザクションの解決」を参照してください)。
	強制アボート 管理者が、イン ダウトのトランザクションを強制的にアボートしました (「MTS トランザクションの解決」を参照してください)。
	コミット中 トランザクションが正しく準備され、MS DTC が関連部分に、トランザクションがコミットされたことを通知しています。MS DTC は、すべての関連部分がコミット要求の受信 (およびログの記録) を確認するまで、そのトランザクションを終了しません。 この時点でトランザクションの結果を変更することはできません。
	アボートを通知できません MS DTC は、すべての接続されている関連部分に、トランザクションがアボートされたことを通知しました。通知を受けていないのは、現在アクセスできない関連部分だけです。 このトランザクション状態は、MS DTC がいずれかのリソース マネージャ (IBM LU 6.2 システムなど) にトランザクションがアボートされたことを通知しなければならないのに、そのシステムとの接続が切断されているため、通知できないときに発生します。 システム管理者は、[トランザクションの一覧] ウィンドウ内でマウスの右ボタンをクリックし、[解決] をポイントします。次に、[破棄] をクリックすると、MS DTC にトランザクションを強制的に破棄させることができます。 警告   トランザクションを手動で破棄する前に、必ず「MTS トランザクションの解決」をお読みください。
	コミットを通知できません MS DTC は、すべての接続されている関連部分に、トランザクションがコミットされたことを通知しました。通知を受けていないのは、現在アクセスできない関連部分だけです。 システム管理者は、[トランザクションの一覧] ウィンドウ内でマウスの右ボタンをクリックし、[解決] をポイントします。次に、[破棄] をクリックすると、MS DTC にトランザクションを強制的に破棄させることができます。 警告   トランザクションを手動で破棄する前に、必ず「MTS トランザクションの解決」をお読みください。
	コミット トランザクションがコミットされ、すべての関連部分が通知を受けました。コミットされたトランザクションは、[トランザクションの一覧] ウィンドウのトランザクションの一覧からすぐに削除されます。 この時点でトランザクションの結果を変更することはできません。
関連項目

MTS トランザクションについて、MTS トランザクションの監視、Windows 95/98 で MTS トランザクションの監視、MTS トランザクションの解決、[トランザクションの一覧] ウィンドウ


MTS トランザクションの解決

MTS トランザクションを管理していると、MTS アプリケーションのトランザクションを手動で解決する必要がある場合があります。トランザクションを解決するには、MTS エクスプローラの [トランザクションの一覧] ウィンドウで、次のいずれかのコマンドを使います。

•	[コミット]   トランザクションを強制的にコミットします。

•	[アボート]   トランザクションを強制的にアボートし、元の状態にロール バックします。

•	[破棄]   コミットまたはアボートされたトランザクションを Microsoft 分散トランザクション コーディネータ (MS DTC) のログから削除します。このコマンドを使う前に、必ずトランザクションを強制的に処理してください。

場合によっては、トランザクションを強制的にコミット、またはアボートしてロックを解除し、データベースのリソースをほかのネットワーク ユーザーやアプリケーションが利用できるようにする必要があります。

たとえば、ネットワーク上の 2 台のコンピュータ間の通信回線に障害が発生すると、この操作が必要になります。トランザクションを手動でコミットまたはアボートしたら、手動でコンピュータにトランザクションを強制的に "破棄" させる必要がある場合があります。破棄すると、ローカルの MS DTC ログ ファイルからトランザクションが削除されます。

次の図は、トランザクションを手動でコミットする場合を示しています。この例では、次の条件を想定しています。

•	コンピュータ A の MS DTC がコミット コーディネータです。

•	2 フェーズ コミット プロトコルが実行される通信回線では、コンピュータ A から コンピュータ D へ順番に通信が進行します。

•	2 フェーズ コミット プロトコルの第 1 フェーズが完了し、MS DTC は COMMITTED レコードをログに書き込みました。

•	2 フェーズ コミット プロトコルの第 2 フェーズの途中で、コンピュータ B とコンピュータ C の間の通信に障害が発生しました。

トランザクションは、次のような未解決状態のままになっています。

コンピュータ A とコンピュータ B の間の通信回線がまだ機能しているため、B もトランザクションをコミットしました。しかし、コンピュータ C とコンピュータ D がトランザクションをコミットしたことを確認するまで、A と B のいずれのコンピュータも各自のログ ファイルに COMMITTED レコードを保持しておかなければなりません。トランザクションを解決し、コンピュータ C とコンピュータ D のデータベースのロックを解除するために、システム管理者は、コンピュータ C に強制的にトランザクションをコミットさせます (次の図を参照してください)。

コンピュータ C とコンピュータ D の間の通信回線がまだ機能しているため、コンピュータ C の強制コミットによって、コンピュータ D はトランザクションをコミットできるようになります。コンピュータ D は、データベースのロックを解除し、トランザクションを破棄することができるようになります。コンピュータ D がトランザクションをコミットし、破棄したことをコンピュータ C が確認すると、コンピュータ C もロックを解除し、トランザクションを破棄することができます。

これで、すべてのコンピュータでトランザクションがコミットされました。ただし、コンピュータ C がコンピュータ B にコミットを通知できないので、コンピュータ B はトランザクションを引き続き保持していなければなりません。コンピュータ B がトランザクションを破棄していないので、コンピュータ A もトランザクションを保持していなければなりません。トランザクションを完了するために、システム管理者は、コンピュータ B に強制的にトランザクションを破棄させます (次の図を参照してください)。コンピュータ B の強制破棄によって、コンピュータ A もトランザクションを破棄できるようになります。これで、2 フェーズ コミット プロトコルが手動で終了し、トランザクションが完了します。

重要   2 フェーズ コミット プロトコルの引き渡し、受け取り通信パターンの性質上、手動でトランザクションを解決する場合は、通信が遮断された位置に最も近いコンピュータで解決することをお勧めします。したがって、上の例では、コンピュータ D ではなくコンピュータ C で強制コミットを行い、コンピュータ A ではなくコンピュータ B で強制破棄を行っています。

通常、トランザクションに関係するシステムや回線に障害が発生した場合は、システムが再起動され、回線が復旧したときに MS DTC が自動的にトランザクションを解決します。システムが再起動されなかったり、回線が復旧しなかったりすると、MS DTC はトランザクションを解決できません。この場合、[イン ダウト]、[アボートを通知できません]、または [コミットを通知できません] の状態のトランザクションを手動で解決することができます。

[イン ダウト] の状態

[イン ダウト] の状態は、トランザクションが子 MS DTC に存在し、MS DTC が準備完了の状態で、親 MS DTC にアクセスできないことを示します。イン ダウトのトランザクションを解決するには、次の手順に従って操作します。

1	[トランザクションの一覧] ウィンドウで、イン ダウトのトランザクションの直接の親を探します。直接の親を探すには、トランザクションをマウスの右ボタンでクリックし、[プロパティ] をクリックします。トランザクションの親 MS DTC コンピュータと子 MS DTC コンピュータが表示されます。

2	親 MS DTC を探し、親コンピュータの [トランザクションの一覧] ウィンドウで、イン ダウトのトランザクションの結果を調べます。

•	トランザクションが [トランザクションの一覧] ウィンドウに表示されていない場合、そのトランザクションはアボートされており、子コンピュータ上でトランザクションを手動でアボートできます。

•	トランザクションが親コンピュータ上で [コミットを通知できません] と表示されている場合、そのトランザクションはコミットされており、子コンピュータ上でトランザクションを手動でコミットできます。

•	トランザクションが親コンピュータ上で [アボートを通知できません] と表示されている場合、そのトランザクションはアボートされており、子コンピュータ上でトランザクションを手動でアボートできます。

•	トランザクションが親コンピュータで [イン ダウト] と表示されている場合は、親コンピュータの [トランザクションの一覧] ウィンドウで、そのトランザクションの次に近い親を探します。トランザクションが表示されない (アボートされている) か、[アボートを通知できません] の状態になっている (アボートされている) か、または [コミットを通知できません] の状態になっている (コミットされている) かのいずれかの親コンピュータが見つかるまで、コミット ツリーをさかのぼってトランザクションをたどります。トランザクションが親コンピュータでアボートされている場合は、そのコンピュータの直接の子コンピュータでトランザクションを手動で強制的にアボートします。トランザクションが親コンピュータでコミットされている場合は、そのコンピュータの直接の子コンピュータでトランザクションを手動で強制的にコミットします。

3	子コンピュータでトランザクションを手動でコミットまたはアボートしたら、直接の親コンピュータに手動で強制的にトランザクションを破棄させます。

[コミットを通知できません]

[コミットを通知できません] の状態は、トランザクションがコミットされたにもかかわらず、一部の従属 MS DTC に通知されなかったことを示します。次の手順に従って、トランザクションを手動で解決できます。[コミットを通知できません] の状態のトランザクションをマウスの右ボタンでクリックします。そのトランザクションの親 MS DTC と従属 MS DTC が表示されます。従属 MS DTC が見つかったら、各 MS DTC でトランザクションを強制的にコミットします。すべての従属 MS DTC でトランザクションを手動でコミットしたら、トランザクションが [コミットを通知できません] と表示されている MS DTC に戻り、その MS DTC に強制的にトランザクションを破棄させます。

警告   すべての従属 MS DTC にトランザクションの結果が通知されるまでは、手動でトランザクションを破棄しないでください。

[アボートを通知できません]

[アボートを通知できません] の状態は、トランザクションがアボートされたにもかかわらず、一部の従属 MS DTC に通知されなかったことを示します。この状態は、[アボート中] の状態とまったく同じです。次の手順に従って、トランザクションを手動で解決できます。[アボートを通知できません] の状態のトランザクションをマウスの右ボタンでクリックします。そのトランザクションの親 MS DTC と従属 MS DTC が表示されます。従属 MS DTC が見つかったら、各 MS DTC でトランザクションを強制的にアボートします。すべての従属 MS DTC でトランザクションを手動でアボートしたら、トランザクションが [アボートを通知できません] と表示されている MS DTC に戻り、その MS DTC に強制的にトランザクションを破棄させます。

警告   すべての従属 MS DTC にトランザクションの結果が通知されるまでは、手動でトランザクションを破棄しないでください。

トランザクションを解決するには

1	MTS エクスプローラのウィンドウの左側で、トランザクションを解決するコンピュータを選択します。

2	[トランザクションの一覧] アイコンをダブルクリックします。

3	ウィンドウの右側で、解決するトランザクションをマウスの右ボタンでクリックします。

4	[解決] をポイントし、[コミット]、[アボート] または [破棄] をクリックします。

関連項目

MTS トランザクションについて、MS DTC の管理、MTS トランザクションの監視、Windows 95/98 で MTS トランザクションの監視、MTS トランザクションの状態について、[トランザクションの一覧] ウィンドウ


MTS 管理の自動化

Microsoft Transaction Server (MTS) 開発者と上級 Web 管理者は、管理スクリプト オブジェクトを使って、MTS アプリケーションの配置と管理を自動化できます。スクリプト オブジェクトは、Microsoft Transaction Server エクスプローラのコレクションの階層に対応しています。適切な "管理スクリプト オブジェクト" でインターフェイスを呼び出すことによって、管理作業を自動化することができます。次の図は、MTS エクスプローラによって管理および配置されるコレクションの種類を示しています。

管理スクリプト オブジェクトを効率的に使うために、アプリケーションによって自動化される MTS エクスプローラの作業を十分に理解してください。管理スクリプト オブジェクトは、IDispatch インターフェイスから派生しているので、オートメーション互換の任意の言語を使って、アプリケーションを開発できます。ActiveXｮ テクノロジおよび COM をサポートしている Microsoftｮ Visual Basicｮ Version 5.0 以降および Microsoftｮ Visual C++ｮ Version 5.0 以降を開発ツールとして使うことをお勧めします。管理スクリプト オブジェクトの使い方を Visual Basic のサンプルについては、「MTS Administrative Reference (管理リファレンス)」を参照してください。

ここでは、次のトピックについて説明します。

MTS 管理オブジェクト

MTS 管理自動化 Visual Basic Script サンプル

MTS 管理自動化 Visual Basic サンプル アプリケーション

Visual Basic による MTS 管理の自動化

Visual Basic による高度な MTS 管理の自動化

関連項目

MTS Administrative Reference (管理リファレンス)


MTS 管理オブジェクト

MTS の管理には、次のスクリプト オブジェクトを使います。

Catalog オブジェクト

CatalogObject オブジェクト

CatalogCollection オブジェクト

PackageUtil オブジェクト

ComponentUtil オブジェクト

RemoteComponentUtil オブジェクト

RoleAssociationUtil オブジェクト

これらのオブジェクトは、さまざまなスクリプトの要求に応じて、汎用インターフェイスとユーティリティ インターフェイスを提供します。Catalog オブジェクト、CatalogObject オブジェクト、および CatalogCollection オブジェクトは、カタログ コレクション オブジェクト層を構成し、オブジェクトの作成や変更など、最上位レベルの機能を提供します。Catalog オブジェクトを使うと、特定のサーバーに接続し、コレクションにアクセスすることができます。CatalogCollection オブジェクトを呼び出すことによって、オブジェクトの列挙、作成、削除、および変更を行ったり、関連するコレクションにアクセスしたりできます。CatalogObject オブジェクトは、オブジェクトのプロパティの取得と設定を行うときに使います。

カタログ ユーティリティ オブジェクト層では、PackageUtil オブジェクト、ComponentUtil オブジェクト、RemoteComponentUtil オブジェクト、および RoleAssociationUtil オブジェクトを使って、コンポーネントの組み込みやパッケージのエクスポートなど、特定の作業を自動化することができます。このユーティリティ層では、ユーザーまたはユーザーのクラスとロールとの関連付けなど、コレクションに対する特定の作業を処理するプログラムを作成できます。

次の図は、構成用のプログラムが管理オブジェクトのメソッドを使って、カタログのデータの読み込み、および書き込みを行う方法を示しています。

管理オブジェクトのサンプルとリファレンス ドキュメントの入手方法については、「開発者用サンプルとドキュメントのインストール」を参照してください。

関連項目

MTS Administrative Reference (管理リファレンス)

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS カタログ コレクション オブジェクトを使う

MTS エクスプローラの各フォルダは、カタログに保存されている各コレクションに対応します。Catalog オブジェクト、CatalogObject オブジェクト、および CatalogCollection オブジェクトは、カタログ コレクション オブジェクト層を構成します。これらのオブジェクトを使うと、コレクションの作成、削除、または変更などの一般的な管理作業を自動化し、アプリケーションに組み込むことができます。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS CatalogCollection オブジェクトのインスタンスを生成する

MTS エクスプローラのフォルダ内の任意のコレクションまたはデータにアクセスするために、CatalogCollection オブジェクトのインスタンスを生成することができます。CatalogCollection オブジェクトのインスタンスを生成するには、GetCollection メソッドを使用し、コレクション名を渡します。CatalogCollection オブジェクトは、MTS エクスプローラのフォルダ内のデータなど、任意のコレクションにアクセスするために使われる汎用オブジェクトです。Catalog オブジェクトから GetCollection メソッドを呼び出し、最上位レベルのコレクションを取得することができます。また、CatalogCollection オブジェクトから GetCollection メソッドを呼び出して関連するコレクションを取得することもできます。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS CatalogCollection オブジェクトにデータを挿入する

CatalogCollection オブジェクトにカタログのデータを挿入するには、管理オブジェクトを使います。オブジェクトのインスタンスを生成しただけでは、カタログのデータは読み込まれません。コレクション内でデータを参照または変更するには、まず Populate メソッドまたは PopulateByKey メソッドを呼び出します。Populate メソッドは、すべてのデータをコレクションに読み込みます。PopulateByKey メソッドは、指定したオブジェクトだけを読み込みます。コレクションにデータを追加したり、ユーティリティ オブジェクト インターフェイスを使用したりする場合は、コレクションにデータを挿入する必要はありません。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS オブジェクトの取得およびプロパティの取得と設定

CatalogCollection オブジェクトは、コレクション内のオブジェクトに対する繰り返し処理をサポートしています。開発ツールとして Visual Basic を使っている場合は、For Each ステートメントを使って繰り返し処理を行うことができます。Visual C++ を使っている場合は、Item メソッドと Count メソッドを呼び出してコレクション内のオブジェクトを列挙します。オブジェクトのプロパティにアクセスするには、オブジェクトの Value プロパティを使って、プロパティ名をパラメータとして渡します。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


新しい MTS オブジェクトの作成

一部のコレクションでは、Add メソッドによる新しいオブジェクトの作成をサポートしています。そのほかのコレクションでは、ユーティリティ インターフェイスを使って、オブジェクト (コンポーネントなど) をインストールする必要があります。詳細については、「MTS カタログ ユーティリティ オブジェクトを使う」を参照してください。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS オブジェクトへの変更を保存する

プロパティの変更、(Add メソッドによって作成された) 新しいオブジェクト、オブジェクトの削除 (ほとんどのコレクションがサポートしている Remove メソッドによる削除) は、SaveChanges メソッドを呼び出すまで、メモリに保存されています。SaveChanges メソッドを呼び出すと、CatalogCollection オブジェクトに加えられたすべての変更がカタログに適用されます。SaveChanges メソッドを呼び出す前に、CatalogCollection オブジェクトを解放したり、Populate メソッドまたは PopulateByKey メソッドを呼び出したりすると、メモリに保存されているそれまでの変更はすべて失われます。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS カタログ ユーティリティ オブジェクトを使う

カタログ ユーティリティ オブジェクト層は、PackageUtil オブジェクト、ComponentUtil オブジェクト、RemoteComponentUtil オブジェクト、および RoleAssociationUtil オブジェクトから構成されます。これらのオブジェクトは、カタログに対して特定の作業 (コンポーネントの組み込みや既成のパッケージのインストールなど) を直接行うときに使います。ユーティリティ オブジェクトは、コレクションの種類に対応しています。ユーティリティ オブジェクトを取得するには、CatalogCollection オブジェクト上で GetUtilInterface メソッドを呼び出します。

ユーティリティ オブジェクトを使った場合、カタログに加えられた変更は、ユーティリティ オブジェクトの取得元の CatalogCollection オブジェクトには反映されません。変更を確認するには、CatalogCollection オブジェクト上で Populate メソッドまたは PopulateByKey メソッドを呼び出さなければなりません。変更はすぐにカタログに書き込まれるので、ユーティリティ メソッドを使った後で SaveChanges メソッドを呼び出す必要はありません。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods


MTS カタログのエラー処理

カタログ コレクション メソッドとカタログ ユーティリティ メソッドは、成功または失敗を示す HRESULT を返します。Visual Basic Version 5.0 では、On Error ステートメントと Err オブジェクトを使ってこれらのエラーをトラップし、エラー コードにアクセスします。多くのオブジェクトを扱うメソッド (SaveChanges メソッドや InstallPackage メソッドなど) では、特定のオブジェクトのエラーを説明する複数のエラー コードが取り込まれることがあります。このコードのセットにアクセスするには、ErrorInfo コレクションを使います。ErrorInfo コレクションにアクセスするには、GetCollection メソッドを使います。ユーザーが生成する CatalogCollection オブジェクトの各インスタンスは、最後に失敗したメソッド呼び出しのエラー コードが格納された ErrorInfo コレクションを保持しています。パッケージをインストールしているときは、そのオブジェクトの ErrorInfo コレクションにアクセスすることによって、どのコンポーネントが既に組み込まれているかを確認することができます。

アプリケーションを作成するときは、各メソッド呼び出しが成功したか、または失敗したかをチェックするようにプログラミングすることをお勧めします。特に、コレクション名またはプロパティ名を渡すときは、プログラムで E_INVALIDARG リターン コード (Visual Basic Version 5.0 ではランタイム エラー 5) をテストしてください。このコードは、渡されたコレクション名またはプロパティ名のうち、1 つまたは複数がサポートされていないことを示します。

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、MTS ErrorInfo Collection


MTS 管理自動化 Visual Basic Script サンプル

Visual Basic Scripting Edition (VBScript) などのオートメーション互換の言語を使って、管理スクリプト オブジェクトを呼び出すことができます。MTS には、管理スクリプト オブジェクトを使って MTS エクスプローラの処理を自動化する方法を示す管理オブジェクト サンプル スクリプトが用意されています。

HTML ページ以外で自動化スクリプトを実行するには、使用しているコンピュータに Windowsｮ Scripting Host (WSH) をインストールしなければなりません。WSH は、コマンドライン スクリプト ユーティリティで、Windows NT 4.0 Option Pack を使って Windows NT コンピュータにインストールできます。WSH を使うと、スクリプトを直接 Windows のデスクトップ上で、またはコマンド プロンプトから実行できます。スクリプトを HTML ドキュメントに埋め込む必要はありません。スクリプトは、デスクトップ上でスクリプト ファイルをダブルクリックすることによって、またはコマンド プロンプトから実行できます。詳細については、Windows Scripting Host のドキュメントを参照してください。

管理オブジェクトをスクリプトでどのように使用するかを理解するために、\Program Files\Mts\Samples\wsh ディレクトリにあるサンプル スクリプトを実行します。このディレクトリには、VB Script で記述された次の 5 つのサンプル スクリプトが含まれています。

•	InstDLL.vbs

•	InstPak.vbs

•	Uninst.vbs

•	InstDllCLI.vbs

•	InstPakCLI.vbs

これらのスクリプトは、Sample Bank の管理作業を自動化します。たとえば、InstDLL.vbs スクリプトは、スクリプト オブジェクトを呼び出して次の作業を行います。まず Sample Bank の既存のバージョンを削除し、Sample Bank という名前の新しいパッケージを作成します。次に、Sample Bank の Visual Basic DLL、Visual C++ DLL、および Visual J++ DLL からコンポーネントを新しいパッケージに組み込み、トランザクション属性を変更します。次に、新しいロールを追加します。InstPak.vbs スクリプトは、スクリプト オブジェクトを使って Sample Bank をインストールし、Uninst.vbs は、MTS から Sample Bank パッケージを削除する作業を自動化します。スクリプトを実行したら、ツール バーの [最新の情報に更新] ボタンをクリックした後、MTS エクスプローラでスクリプトの結果を確認することができます。

InstDLL.vbs スクリプト、InstPak.vbs スクリプト、および Uninst.vbs スクリプトを使うには、スクリプト内のファイルのパスが自分のコンピュータ上の必要なファイルの場所を指すように変更しなければなりません。たとえば、InstPak.vbs スクリプト内のファイルのパスは、次に示す Sample Bank パッケージの既定の場所です。

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

Sample Bank パッケージが別の場所にインストールされている場合は、スクリプト内の該当する行を変更して現在のパッケージの場所を指すようにします。

InstDllCLI.vbs スクリプトと InstPakCLI.vbs スクリプトは、コマンドライン パラメータをサポートしているので、コマンド プロンプトでスクリプトを実行するときにファイルの場所をパラメータとして入力することができます。コマンド プロンプトで、使用するスクリプトが含まれているディレクトリに移動し、スクリプト名とパッケージまたは DLL の場所を入力します。たとえば、既定のディレクトリにある Sample Bank パッケージをインストールするには、サンプル スクリプトが含まれているディレクトリに移動し、コマンド プロンプトで次のコマンドを使用します。

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

InstDLL.vbs スクリプトを使うには、まず、次の操作を実行して Vjacct.dll ファイルに Java コンポーネントを登録しなければなりません。

•	Microsoftｮ Visual Studioｮ 97 の ActiveX ウィザードを使って、Java コンポーネントを登録する。

関連項目

管理オブジェクト サンプル スクリプトのセットアップ


MTS 管理自動化 Visual Basic サンプル アプリケーション

Visual Basic Version 5.0 サンプル アプリケーションは、Catalog オブジェクト、CatalogObject オブジェクト、および CatalogCollection オブジェクト上でメソッドを使うことにより、"Scriptable Admin Demo" という名前のパッケージの基本的な管理機能を自動化する方法を示します。

注    作成する Visual Basic Version 5.0 のプロジェクトが MTS 管理タイプ ライブラリ (MTSAdmin タイプ ライブラリ) を参照するように構成しなければなりません。MTSAdmin タイプ ライブラリを参照するには、Visual Basic の [プロジェクト] メニューの [参照設定] をクリックします。次に、利用できる参照ファイルの中の "MTS 2.0 Admin Type Library" を探します。実行時バインディング変数 (プログラムの実行時に生じるバインディング) に対応するタイプ ライブラリは、使用しているローカル コンピュータに MTXADMIN.DLL ファイルがインストールされていれば、特に構成作業を行わなくても Visual Basic が探します。

"Scriptable Admin Demo" という名前の既存のパッケージをすべて削除するには

1	CreateObject メソッドを呼び出してカタログオブジェクトのインスタンスを生成します。

    Dim catalog As Object

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

2	GetCollection メソッドを呼び出して Packages コレクション オブジェクトを取得します。Packages コレクションは、カタログからデータを取得せずに戻るので、GetCollection メソッドから戻ったとき、コレクションは空になっています。

    Dim packages As Object

    Set packages = catalog.GetCollection("Packages")

3	すべてのパッケージを読み込んで Packages コレクションに挿入し、"Scriptable Admin Demo" を検索することによって、前のバージョンの "Scriptable Admin Demo" パッケージを探します。最大のインデックスから開始してコレクション内を列挙し、ループの中から Remove メソッドを呼び出すことができるようにします。Remove メソッドは、オブジェクトを解放し、コレクションからオブジェクトを削除します。また、削除されるインデックス以上のすべての n に対応するオブジェクト (n+1) が オブジェクト (n) になるように、コレクション内のオブジェクトをシフトします。Remove メソッドがコレクション オブジェクトに及ぼす影響はすぐに反映されます。Remove メソッドが呼び出された後、Item メソッドや Count メソッドは、どの時点で呼び出されても、インデックスの変更が反映されます。ただし、パッケージの削除は、SaveChanges メソッドが呼び出されるまで、カタログには適用されません (手順 4 を参照)。

    packages.Populate

    n = packages.Count

    For i = n - 1 To 0 Step -1

        If packages.Item(i).Value("Name") = "Scriptable Admin Demo" Then

        packages.Remove (i)

        End If

    Next

4	SaveChanges メソッドを呼び出して変更をデータ格納場所に保存します。

    packages.SaveChanges

"Scriptable Admin Demo" という名前の新しいパッケージを作成するには

1	Add メソッドを使って新しいパッケージを追加し、割り当てられたパッケージ ID を記録します。Add メソッドは、コレクションにオブジェクトを追加しますが、SaveChanges メソッドが呼び出されるまで、変更はカタログに適用されません (手順 3 を参照)。Add メソッドでは、すべてのプロパティに既定値が適用されることに注意してください。既定の ID は、新しい一意の ID になります。

    Dim newPack As Object

    Dim newPackID As Variant

    Set newPack = packages.Add

    newPackID = newPack.Value("ID")

2	Name プロパティと SecurityEnabled プロパティを更新します。

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

    newPack.Value("SecurityEnabled") = "N"

3	SaveChanges メソッドを呼び出して新しいパッケージをカタログに保存します。この呼び出しの戻り値は、変更、追加、または削除されたオブジェクトの数です。変更がない場合、メソッドは 0 を返します。

    n = packages.SaveChanges

"Scriptable Admin Demo" という名前のパッケージのプロパティを更新し、ComponentsInPackage コレクションを取得するには

1	PopulateByKey メソッドを呼び出してカタログからパッケージを読み込みます。読み込むオブジェクトのキーを含む配列を渡します。サンプル コードでは、1 つの要素 (作成したばかりのパッケージの ID) を含む配列を使っています。

    Dim keys(0) as Variant

    keys(0) = newPackId

    packages.PopulateByKey keys

2	コレクションからパッケージ オブジェクトを取得します。

    Dim package As Object

    Set package = packages.Item(0)

3	パッケージの SecurityEnabled プロパティを更新します。

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

4	GetCollection メソッドを呼び出して ComponentsInPackage コレクションを取得します。"Scriptable Admin Demo" パッケージのキーをパラメータとして渡します。

    Dim components As Object

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

5	SaveChanges メソッドを呼び出して変更をカタログに保存します。

    packages.SaveChanges

コンポーネントを "Scriptable Admin Demo" パッケージに組み込むには

1	GetUtilInterface メソッドを呼び出してコンポーネント ユーティリティ オブジェクトを取得します。このオブジェクトはコンポーネントの組み込みに使います。

    Dim util As Object

    Set util = components.GetUtilInterface

    On Error GoTo installFailed

2	組み込むコンポーネントのダイナミック リンク ライブラリ (DLL) の名前を含む文字列を渡して InstallComponent メソッドを呼び出します。コンポーネントに外部タイプ ライブラリまたはプロキシ/スタブ DLL がない場合は、空の文字列を第 2 引数と第 3 引数として渡します。新しいコンポーネントを組み込んだ後に SaveChanges メソッドを呼び出す必要はありません。DLL に含まれるすべてのコンポーネントは、このメソッドによって組み込まれ、すぐにカタログに書き込まれます。GetCLSIDs メソッドを呼び出し、組み込まれたコンポーネントのクラス ID (CLSID) を取得します。

    Form2.Show 1

    Dim thePath As String

    thePath = Form2.MTSPath + "･samples･packages･vbacct.dll"

    util.InstallComponent thePath, "", ""

    Dim installedCLSIDs() as Variant

    util.GetCLSIDs thePath, "", installedCLSIDs

    On Error GoTo 0

3	PopulateByKey メソッドを呼び出し、組み込まれたばかりのコンポーネントを読み込みます。InstallComponent メソッドを使ってパッケージに組み込んだコンポーネントは、Populate メソッドまたは PopulateByKey メソッドを呼び出してカタログからデータを読み込むまで、コレクション内では表示されません。

    components.PopulateByKey installedCLSIDs

"Scriptable Admin Demo" パッケージから Bank.CreateTable コンポーネントを探して削除するには

1	Item メソッドと Count メソッドを使って、コンポーネントに繰り返し処理を行い、トランザクション属性を変更します。

    Dim component As Object

    n = components.Count

    For i = n - 1 To 0 Step -1

        Set component = components.Item(i)

        component.Value("Transaction") = "Required"

2	インデックスを使って Bank.CreateTable コンポーネントを探し、削除します。ループの中で Remove メソッドを呼び出すには、コレクション内を逆方向に繰り返し処理を行わなければならないことに注意してください。

        If component.Value("ProgID") = "Bank.CreateTable" Then

            components.Remove (i)

        End If

    Next

3	新しい総数を取得し、コレクション内でもう一度繰り返し処理を行います。SaveChanges メソッドを呼び出すまで、Bank.CreateTable コンポーネントはデータ格納場所から削除されません。組み込みが成功した場合は、ユーザーに知らせるメッセージを表示します。

    n = components.Count

    For i = 0 To n - 1

        Set component = components.Item(i)

        Debug.Print component.Value("ProgID")

        Debug.Print component.Value("DLL")

    Next

    n = components.SaveChanges

    MsgBox "Scriptable Admin Demo package installed and configured."

    Exit Sub

installFailed:

    MsgBox "Error code " + Str$(Err.Number) + " installing " + thePath + "  Make sure the MTS path you entered is correct and that vbacct.dll is not already installed."

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化、Visual Basic による高度な MTS 管理の自動化


Visual Basic による MTS 管理の自動化

管理スクリプト オブジェクトは、パッケージとコンポーネントのインストール、削除、およびプロパティの更新に使用できます。以下のトピックでは、管理スクリプト オブジェクト上でメソッドを使うことによって、次の管理作業を自動化するための手順と Microsoftｮ Visual Basicｮ Version 5.0 のサンプル コードについて説明します。

•	既成の MTS パッケージのインストールを自動化する

•	新しい MTS パッケージの作成とコンポーネントの組み込みを自動化する

•	インストールされた MTS パッケージを列挙し、プロパティを更新する作業を自動化する

•	インストールされた MTS パッケージを列挙し、パッケージを削除する作業を自動化する

•	インストールされた MTS コンポーネントを列挙し、コンポーネントを削除する作業を自動化する

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による高度な MTS 管理の自動化


既成の MTS パッケージのインストールを自動化する

"Test.pak" という名前の既成のパッケージを MTS エクスプローラにインストールするには

1	既成のパッケージのインストールに使うオブジェクトを宣言します。

Private Sub InstallPackage_Click()

    Dim catalog As Object

    Dim packages As Object

    Dim util As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して最上位レベルの Packages コレクションを取得します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

4	PackageUtil オブジェクトのインスタンスを生成し、InstallPackage メソッドを呼び出して "test.pak" という名前のパッケージをインストールします。

    Set util = packages.GetUtilInterface

    util.InstallPackage "c:･test.pak", "", 0

    Exit Sub

5	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による高度な MTS 管理の自動化


新しい MTS パッケージの作成とコンポーネントの組み込みを自動化する

"My Package" という名前の新しいパッケージを作成し、そのパッケージにコンポーネントを組み込むには

1	新しいパッケージのインストールとそのパッケージへのコンポーネントの組み込みに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim newPack As Object

    Dim componentsInNewPack As Object

    Dim util As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して最上位レベルの Packages コレクションを取得します。次に、Add メソッドを呼び出して新しいパッケージを追加します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    Set newPack = packages.Add

    Dim newPackID As String

4	パッケージ名を "My Package" に設定し、変更を Packages コレクションに保存します。

    newPackID = newPack.Key

    newPack.Value("Name") = "My Package"

    packages.SaveChanges

5	GetCollection メソッドを呼び出して ComponentsInPackage コレクションにアクセスします。次に、ComponentUtil オブジェクトのインスタンスを生成し、InstallComponent メソッドを呼び出して新しいパッケージにコンポーネントを組み込みます。

    Set componentsInNewPack = packages.GetCollection("ComponentsInPackage", newPackID)

    Set util = componentsInNewPack.GetUtilInterface

    util.InstallComponent"d:･dllfilepath", "", ""

    Exit Sub

6	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による高度な MTS 管理の自動化


インストールされた MTS パッケージを列挙し、プロパティを更新する作業を自動化する

インストールされたパッケージを列挙し、"My Package" という名前のパッケージのプロパティを更新するには

1	インストールされたパッケージを列挙し、パッケージのプロパティを更新するときに使うオブジェクトを宣言します。

Private Sub BrowseUpdate_Click()

    Dim catalog As Object

    Dim packages As Object

    Dim pack As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。次に、Populate メソッドを呼び出してカタログのパッケージをコレクションに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    packages.Populate

4	コレクション内を列挙し、"My Package" という名前のパッケージを探します。"My Package" が見つかったら、SecurityEnabled プロパティを "Y" に設定します。SaveChanges メソッドを呼び出してパッケージのプロパティの更新を保存します。

    For Each pack In packages

        If pack.Name = "My Package" Then

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

            Exit For

        End If

    Next

    packages.SaveChanges

    Exit Sub

5	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による高度な MTS 管理の自動化


インストールされた MTS パッケージを列挙し、パッケージを削除する作業を自動化する

インストールされたパッケージを列挙し、"My Package" という名前のパッケージを削除するには

1	インストールされたパッケージを列挙し、特定のパッケージを削除するときに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim pack As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。次に、Populate メソッドを呼び出し、カタログにインストールされているパッケージをコレクションに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    packages.Populate

4	Count メソッドと Item メソッドを使ってパッケージ コレクション内を列挙し、"My Package" という名前のパッケージを探します。"My Package" が見つかったら、Remove メソッドを呼び出してパッケージを削除します。次に、SaveChanges メソッドを呼び出して変更をコレクションに保存します。

    For i = 0 To packages.Count-1

        Set pack = packages.Item(i)

        If pack.Name = "My Package" Then

            packages.Remove (i)

            packages.savechanges

            Exit For

        End If

    Next

    Exit Sub

5	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による高度な MTS 管理の自動化


インストールされた MTS コンポーネントを列挙し、コンポーネントを削除する作業を自動化する

インストールされたコンポーネントを列挙し、コンポーネントを削除するには

1	インストールされたコンポーネントを列挙し、特定のコンポーネントを削除するときに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim pack As Object

    Dim componentsInPack As Object

    Dim comp As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。次に、Populate メソッドを呼び出してカタログにインストールされているパッケージをコレクションに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    packages.Populate

4	コレクション内を列挙し、"My Package" という名前のパッケージを探します。次に、GetCollection メソッドを呼び出して ComponentsInPackage コレクションを取得します。Populate メソッドを使って ComponentsInPackage コレクションにコンポーネントを挿入し、コレクション内を列挙し、"Bank.Account" コンポーネントを探します。Remove メソッドを呼び出してコンポーネントを削除し、SaveChanges メソッドを呼び出して変更をコレクションに保存します。

    For Each pack In packages

        If pack.Name = "My Package" Then

            Set componentsInPack = packages.GetCollection("ComponentsInPackage", pack.Key)

            componentsInPack.Populate

            For i = 0 To componentsInPack.Count

                Set comp = componentsInPack.Item(i)

                If comp.Name = "Bank.Account" Then

                    componentsInPack.Remove (i)

                    componentsInPack.savechanges

                    Exit For

                End If

            Next

            Exit For

        End If

    Next

    Exit Sub

5	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による高度な MTS 管理の自動化


Visual Basic による高度な MTS 管理の自動化

管理スクリプト オブジェクトは、クライアントとロールの構成、パッケージのエクスポート、およびカタログがサポートするコレクションとプロパティの名前へのアクセスに使用できます。以下のトピックでは、管理スクリプト オブジェクト上でメソッドを使うことによって、次の管理作業を自動化するための手順と Visual Basic Version 5.0 のサンプル コードについて説明します。

•	MTS 関連コレクション名へのアクセスを自動化する

•	MTS プロパティ情報へのアクセスを自動化する

•	MTS ロールの構成を自動化する

•	MTS パッケージのエクスポートを自動化する

•	リモート コンポーネントを使うように MTS クライアントを構成する作業を自動化する

•	リモート サーバー上で MTS パッケージのプロパティを更新する作業を自動化する


MTS 関連コレクション名へのアクセスを自動化する

RelatedCollectionInfo コレクションには、1 つのコレクションからアクセスできる関連コレクションの一覧が格納されています。このコレクションがサポートするプロパティの一覧については、「MTS Administrative Reference (管理リファレンス)」の RelatedCollectionInfo コレクションのトピックを参照してください。

関連コレクション名にアクセスし、関連コレクション名を表示するには

1	関連コレクションの名前が格納されているオブジェクトへのアクセスに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim RelatedCollectionInfo As Object

    Dim collName As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。次に、Packages コレクション オブジェクト上で GetCollection メソッドを呼び出して RelatedCollectionInfo コレクションを取得します。GetCollection メソッドを呼び出して RelatedCollectionInfo コレクションにアクセスするときは、キー値を空白のままにしてください。RelatedCollectionInfo コレクションの情報は、どのパッケージでも同じなので、キー値は使われません。Populate メソッドを呼び出してカタログの情報を RelatedCollectionInfo コレクションに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    Set RelatedCollectionInfo = packages.GetCollection("RelatedCollectionInfo", "")

    RelatedCollectionInfo.Populate

4	RelatedCollectionInfo コレクション内を列挙し、各コレクションの名前を表示します。

    For Each collName In RelatedCollectionInfo

        Debug.Print collName.Name

    Next

    Exit Sub

5	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化


MTS プロパティ情報へのアクセスを自動化する

PropertyInfo コレクションには、コレクション内の各プロパティに関する情報が格納されています。このコレクションの詳細については、「MTS Administrative Reference (管理リファレンス)」の PropertyInfo コレクションのトピックを参照してください。

コレクション内の各プロパティにアクセスし、プロパティの名前の一覧を表示するには

1	カタログに格納されているプロパティ情報へのアクセスに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim propertyInfo As Object

    Dim property As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。Packages コレクション上で GetCollection メソッドを呼び出して PropertyInfo コレクションを取得します。GetCollection メソッドを呼び出して PropertyInfo コレクションにアクセスするときは、キー値を空白のままにしてください。PropertyInfo コレクションの情報は、どのパッケージでも同じなので、キー値は使われません。Populate メソッドを呼び出してカタログの情報を PropertyInfo コレクションに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    Set propertyInfo = packages.GetCollection("PropertyInfo", "")

    propertyInfo.Populate

4	PropertyInfo コレクション内を列挙し、コレクション内の各プロパティ名の一覧を表示します。

    For Each property In propertyInfo

        Debug.Print property.Name

    Next

    Exit Sub

5	パッケージのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化


MTS ロールの構成を自動化する

パッケージとコンポーネントのロールを構成し、ユーザーに管理者権限を割り当てるには

1	特定のコンポーネントのロールを構成するときに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim pack As Object

    Dim comp As Object

    Dim newUser As Object

    Dim newRole As Object

    Dim componentsInPack As Object

    Dim RolesInPackage As Object

    Dim usersInRole As Object

    Dim rolesForComponent As Object

    Dim util As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。次に、カタログのデータを Packages コレクションに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    packages.Populate

4	Packages コレクション内を列挙し、"My Package" という名前のパッケージを探します。"My Package" が見つかったら、GetCollection メソッドを呼び出して RolesInPackage コレクションを取得します。Add メソッドを使って、新しいロールをパッケージに追加します。新しいロールに "R1" という名前を付けて変更をコレクションに保存します。

    For Each pack In packages

        If pack.Name = "My Package" Then

            Set rolesInPack = packages.GetCollection("RolesInPackage", pack.Key)

            Set newRole = rolesInPack.Add

            newRole.Value("Name") = "R1"

            rolesInPack.savechanges

5	RolesInPackage コレクション上で GetCollection メソッドを呼び出して UsersInRole コレクションを取得します。Add メソッドを使って、既存の NT ユーザーをロールに追加します。ユーザー名を "administrator" に設定します。変更を UsersInRole コレクションに保存します。

            Set usersInRole = RolesInPackage.GetCollection("UsersInRole", newRole.Key)

            Set newUser = usersInRole.Add

            newUser.Value("User") = "administrator"

            usersInRole.savechanges

6	GetCollection メソッドを呼び出して ComponentsInPackage コレクションを取得します。ComponentsInPackage コレクションにデータを挿入し、コレクション内を列挙し、"Bank Account" コンポーネントを探します。新しいロールをコンポーネントに関連付けるために、GetUtilInterface メソッドを呼び出して RoleAssociationUtil オブジェクトのインスタンスを生成します。次に、AssociateRole メソッドを呼び出して新しいロールをコンポーネントに関連付けます。

            Set componentsInPack = packages.GetCollection("ComponentsInPackage", pack.Key)

            componentsInPack.Populate

            For Each comp In componentsInPack

                If comp.Name = "Bank.Account" Then

                    Set rolesForComponent = componentsInPack.GetCollection("RolesForPackageComponent", comp.Key)

                    Set util = rolesForComponent.GetUtilInterface

                    util.associateRole (newRole.Key)

                    Exit For

                End If

            Next

            Exit For

        End If

    Next

    Exit Sub

7	コンポーネントのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化


MTS パッケージのエクスポートを自動化する

"test.pak" という名前のパッケージをエクスポートするには

1	パッケージのエクスポートに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim pack As Object

    Dim util As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して Packages コレクションを取得します。Populate メソッドを呼び出してカタログのデータをパッケージに挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set packages = catalog.GetCollection("Packages")

    packages.Populate

4	Packages コレクション内を列挙し、"My Package" という名前のパッケージを探します。パッケージが見つかったら、パッケージ ユーティリティ オブジェクトのインスタンスを生成し、ExportPackage メソッドを呼び出します。

    For Each pack In packages

        If pack.Name = "My Package" Then

            Set util = packages.GetUtilInterface

            util.ExportPackage pack.Key, "c:･test.pak", 0

            Exit For

        End If

    Next

    Exit Sub

5	コンポーネントのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化


リモート コンポーネントを使うように MTS クライアントを構成する作業を自動化する

Bank.CreateTable リモート コンポーネントを使うようにクライアントを構成するには

1	リモート コンポーネントを実行するように (MTS を実行している) クライアントを構成するときに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim remoteComps As Object

    Dim util As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。GetCollection メソッドを呼び出して RemoteComponents コレクションを取得します。次に、GetUtilInterface メソッドを使って、RemoteComponentUtil オブジェクトのインスタンスを生成します。リモート コンポーネントを組み込むために、InstallRemoteComponentByName メソッドを呼び出してサーバー コンピュータ名、サーバー上のパッケージ名、およびコンポーネント名を渡します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set remoteComps = catalog.GetCollection("RemoteComponents")

    Set util = remoteComps.GetUtilInterface

    util.InstallRemoteComponentByName "remote1", "New","Bank.CreateTable"

    Exit Sub

4	コンポーネントのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化


リモート サーバー上で MTS パッケージのプロパティを更新する作業を自動化する

"remote1" という名前のリモート コンピュータ上でパッケージのプロパティを更新するには

1	リモート コンポーネントの配置と管理を行うように (MTS を実行している) クライアントを構成するときに使うオブジェクトを宣言します。

    Dim catalog As Object

    Dim packages As Object

    Dim pack As Object

    Dim root As Object

2	メソッドが失敗の HRESULT を返した場合は、On Error ステートメントを使ってランタイム エラーを処理します。On Error ステートメントと Err オブジェクトを使って MTS がトラップできるエラーをテストし、エラーに応答することができます。

    On Error GoTo failed

3	CreateObject メソッドを呼び出して Catalog オブジェクトのインスタンスを生成します。Connect メソッドを呼び出して "remote1" という名前のコンピュータ上の "ルート コレクション" にアクセスします。ルート コレクションは、コンピュータ上の最上位のコレクションにアクセスするためのコレクション オブジェクトです。ルート コレクションにはオブジェクトが含まれていません。また、ルート コレクションにはプロパティがありません。ルート コレクションから GetCollection メソッドを呼び出すときは、キー値を使いません。GetCollection メソッドを呼び出してリモート コンピュータ上の Packages コレクションを取得します。次に、Populate メソッドを使って、パッケージ コレクションにデータを挿入します。

    Set catalog = CreateObject("MTSAdmin.Catalog.1")

    Set root = catalog.Connect("remote1")

    Set packages = root.GetCollection("Packages", "")

    packages.Populate

4	"My Package" の SecurityEnabled プロパティを "Y" に設定し、変更をパッケージ コレクションに保存します。

    For Each pack In packages

        If pack.Name = "My Package" Then

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

            Exit For

        End If

    Next

    packages.savechanges

    Exit Sub

5	コンポーネントのインストールが失敗した場合は、Err オブジェクトを使ってエラー メッセージを表示します。

failed:

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

End Sub

関連項目

Using MTS Administration Objects、Using MTS Collection Types、MTS Administration Object Methods、Visual Basic による MTS 管理の自動化


MTS Overview and Concepts

How Does MTS Work?

Explains the elements of Microsoft Transaction Server and how they work together to provide the infrastructure and programming model to develop and deploy components.

MTS Programming Concepts

Explains the key concepts that a component application developer needs to understand for developing applications.


How Does Microsoft Transaction Server Work?
How Does MTS Work?

This topic describes the elements of Microsoft Transaction Server (MTS) and explains how they provide the infrastructure and programming model to develop and deploy MTS components.

Elements of MTS

Contents

Application Components

MTS Executive

Server Processes

Resource Managers

Resource Dispensers

Microsoft Distributed Transaction Coordinator

MTS Explorer


Application Components

Application components model the activity of a business. These components implement the business rules, providing views and transformations of the application state. Consider, for example, the case of an online bank. Records in one or more database systems represent the durable state of the business, such as the amount of money in an account. The application components update that state to reflect such changes as debits and credits.

MTS shelters developers from complex server issues, allowing them to focus on implementing business functions. Because components running in the MTS run-time environment can take advantage of transactions, developers can write applications as if they run in isolation. MTS handles the concurrency, resource pooling, security, context management, and other system-level complexities. The transaction system, working in cooperation with database servers and other types of resource managers, ensures that concurrent transactions are atomic, consistent, have proper isolation, and that, once committed, the changes are durable. For more information on the benefits of transactions, see Transactions.

MTS also makes it easier to build distributed applications by providing location transparency. MTS automatically loads the component into a process environment. An MTS component can be loaded into a client application process (in-process component), or into a separate surrogate server process environment, either on the client's computer (local component) or on another computer (remote component).

In-process, local, and remote components

MTS Components and COM

MTS components are COM in-process server components contained in (DLLs). They are distinguished from other COM components in that they execute in the MTS run-time environment. You can create and implement these components with Visual Basic, Visual C++, Visual J++, or any ActiveX-compatible development tool.

Note that the term component represents the code that implements a COM object. For example, Visual C++ components are implemented as classes. Likewise, Visual Basic components are implemented by class modules.

MTS imposes specific requirements on components beyond those required by COM (see MTS Component Requirements). This allows MTS to provide services to the component that would not otherwise be possible. These include increased scalability and robustness and simplified system management.

See Also

Base Clients vs. MTS Components, MTS Objects, Business Logic in MTS Components, Server Processes


Transaction Server Executive
MTS Executive

The MTS Executive is a dynamic-link library (DLL) that provides run-time services for MTS components, including thread and context management. This DLL loads into the processes that host application components and runs in the background.

MTS also provides a set of resource dispensers that simplify access to shared resources in a server process. For more information, see Resource Dispensers.

See Also

Application Components


Server Processes

A server process is a system process that hosts the execution of an application component. A server process can host multiple components and can service tens, hundreds, or potentially thousands of clients. You can configure multiple server processes to execute on a single computer. Each server process reflects a separate trust boundary and fault isolation domain.

Other process environments can also host application components. As a result, you can deploy applications that meet varying distribution, performance, and fault isolation requirements. For example, you can configure MTS components to be loaded directly into Microsoft Internet Information Server (IIS). You can also configure them to load directly into client processes.

Server Process


Resource Managers

A resource manager is a system service that manages durable data. 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 isolationto an application.

MTS supports resource managers, such as Microsoft SQL Server version 6.5, that implement the OLE Transactions protocol.

See Also

Resource Dispensers, Microsoft Distributed Transaction Coordinator


Resource Dispensers

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. MTS provides two resource dispensers:

•	The ODBC resource dispenser

•	The Shared Property Manager

ODBC Resource Dispenser

The ODBC resource dispenser manages pools of database connections for MTS components that use the standard ODBC interfaces, allocating connections to objects quickly and efficiently. Connections are automatically enlisted on an object's transactions, and the resource dispenser can automatically reclaim and reuse connections. The ODBC 3.0 Driver Manager is the ODBC resource dispenser; the Driver Manager DLL is installed with MTS.

Shared Property Manager

The Shared Property Manager provides synchronized access to application-defined, process-wide properties (variables). For example, you can use it to maintain a Web-page hit counter or to maintain the shared state for a multiuser game.

See Also

ISharedPropertyGroupManager Interface, Creating a Simple ActiveX Component, Sharing State


Microsoft Distributed Transaction Coordinator

The Microsoft Distributed Transaction Coordinator (MS DTC) is a system service that coordinates transactions. Work can be committed as an atomic transaction even if it spans multiple resource managers, potentially on separate computers.

MS DTC was first released as part of Microsoft SQL Server version 6.5 and is included in MTS, providing a low-level infrastructure for transactions. MS DTC implements a two-phase commit protocol to ensure that the transaction outcome (either commit or abort) is consistent across all resource managers involved in a transaction. MS DTC ensures atomicity, regardless of failures.

See Also

Resource Managers


Microsoft Transaction Server Explorer (Programming Concepts)
MTS Explorer

You can use the MTS Explorer to deploy application components. You can also use it to view and manipulate items in the MTS run-time environment.

For a complete discussion of using the MTS Explorer for application administration, see the Administrator's Guide.


Programming Concepts
MTS Programming Concepts

This topic explains the key concepts that a component application developer needs to understand to develop Microsoft Transaction Server (MTS) applications.

Contents

Transactions

MTS Objects

MTS Clients

Activities

Components and Threading

Programmatic Security

Error Handling


Transactions

MTS simplifies the task of developing application components by allowing you to perform work with transactions. This protects applications from anomalies caused by concurrent updates or system failures.

Transactions maintain the ACID properties:

•	Atomicity ensures that all the updates completed under a specific transaction are committed and made durable, or that they get aborted and rolled back to their previous state.

•	Consistency means that a transaction is a correct transformation of the system state, preserving the state invariants.

•	Isolation protects concurrent transactions from seeing each other's partial and uncommitted results, which might create inconsistencies in the application state. Resource managers use transaction-based synchronization protocols to isolate the uncommitted work of active transactions.

•	Durability means that committed updates to managed resources, such as a database record, survive failures, including communication failures, process failures, and server system failures. Transactional logging even allows you to recover the durable state after disk media failures.

The intermediate states of a transaction are not visible outside the transaction, and either all the work happens or none of it does. This allows you to develop application components as if each transaction executes sequentially and without regard to concurrency. This is a tremendous simplification for application developers.

You can declare that a component is transactional, in which case MTS associates transactions with the component's objects. When an object's method is executed, the services that resource managers and resource dispensers perform on its behalf execute under a transaction. This can also include work that it performs for other MTS objects. Work from multiple objects can be composed into a single atomic transaction.

Multiple objects composed into a transaction

Without transactions, error recovery is extremely difficult, especially when multiple objects update multiple databases. The possible combinations of failure modes are too great even to consider. Transactions simplify error recovery. Resource managers automatically undo the transaction's work, and the application retries the entire business transaction.

Transactions also provide a simple concurrency model. Because a transaction's isolation prevents one client's work from interfering with other clients, you can develop components as though only a single client executes at a time.

Components Declare Transactional Requirements

Every MTS component has a transaction attribute that is recorded in the MTS catalog. MTS uses this attribute during object creation to determine whether the object should be created to execute within a transaction, and whether a transaction is required or optional. For more information on transaction attributes, see Transaction Attributes.

Components that make updates to multiple transactional resources, such as database records, for example, can ensure that their objects are always created within a transaction. If the object is created from a context that has a transaction, the new context inherits that transaction; otherwise, the system automatically initiates a transaction.

Components that only perform a single transactional update can be declared to support, but not require, transactions. If the object is created from a context that has a transaction, the new context inherits that transaction. This allows the work of multiple objects to be composed into a single atomic transaction. If the object is created from a context that does not have a transaction, the object can rely on the resource manager to ensure that the single update is atomic.

How Work Is Associated with a Transaction

An object's associated context object indicates whether the object is executing within a transaction and, if so, the identity of the transaction.

Resource dispensers can use the context object to provide transaction-based services to the MTS object. For example, when an object executing within a transaction allocates a database connection by using the ODBC resource dispenser, the connection is automatically enlisted on the transaction. All database updates using this connection become part of the transaction, and are either atomically committed or aborted. For more information, see Enlisting Resources in Transactions.

Stateful and Stateless Objects

Like any COM object, MTS objects can maintain internal state across multiple interactions with a client. Such an object is said to be stateful. MTS objects can also be stateless, which means the object does not hold any intermediate state while waiting for the next call from a client.

When a transaction is committed or aborted, all of the objects that are involved in the transaction are deactivated, causing them to lose any state they acquired during the course of the transaction. This helps ensure transaction isolation and database consistency; it also frees server resources for use in other transactions.

Completing a transaction enables MTS to deactivate an object and reclaim its resources, thus increasing the scalability of the application. Maintaining state on an object requires the object to remain activated, holding potentially valuable resources such as database connections. Stateless objects are more efficient and are thus recommended. For more information on object deactivation, see Deactivating Objects.

How Objects Can Participate in Transaction Outcome

You can use methods implemented on the IObjectContext interface to enable an MTS object to participate in determining a transaction's outcome. The SetComplete, SetAbort, DisableCommit, and EnableCommit methods work in conjunction with the component's transaction attribute to allow one or more objects to be composed simply and safely within transactions.

•	SetComplete indicates that the object has successfully completed its work for the transaction. The object is deactivated upon return from the method that first entered the context.

•	SetAbort indicates that the object's work can never be committed. The object is deactivated upon return from the method that first entered the context.

•	EnableCommit indicates that the object's work is not necessarily done, but that its transactional updates can be committed in their current form.

•	DisableCommit indicates that the object's transactional updates can not be committed in their current form.

Both SetComplete and SetAbort deactivate the object on return from the method. MTS reactivates the object on the next call that requires object execution.

Objects that need to retain state across multiple calls from a client can protect themselves from having their work committed prematurely by the client. By calling DisableCommit before returning control to the client, the object can guarantee that its transaction cannot successfully be committed without the object doing its remaining work and calling EnableCommit.

Client-Controlled vs. Automatic Transactions

Transactions can either be controlled directly by the client, or automatically by the MTS run-time environment.

Clients can have direct control over transactions by using a transaction context object. The client uses the ITransactionContext interface to create MTS objects that execute within the client's transactions, and to commit or abort the transactions.

Transactions can automatically be initiated by the MTS run-time environment to satisfy the component's transaction expectations. MTS components can be declared so that their objects always execute within a transaction, regardless of how the objects are created. This feature simplifies component development, because you do not need to write application logic to handle the special case where an object is created by a client not using transactions.

This feature also reduces the burden on client applications. Clients do not need to initiate a transaction simply because the component that they are using requires it.

MTS automatically initiates transactions as needed to satisfy a component's requirements. This event occurs, for example, when a client that is not using transactions creates an object in an MTS component that is declared to require transactions.

MTS completes automatic transactions when the MTS object that triggered their creation has completed its work. This event occurs when returning from a method call on the object after it has called SetComplete or SetAbort. SetComplete causes the transaction to be committed; SetAbort causes it to be aborted.

A transaction cannot be committed while any method is executing in an object that is participating in the transaction. The system behaves as if the object disables the commit for the duration of each method call.

See Also

Building Transactional Components, Multiple Transactions


Transaction Attributes

Every MTS component has a transaction attribute. The transaction attribute can have one of the following values:

•	Requires a transaction. This value indicates that the component's objects must execute within the scope of a transaction. When a new object is created, its object context inherits the transaction from the context of the client. If the client does not have a transaction, MTS automatically creates a new transaction for the object.

•	Requires a new transaction. This value indicates that the component's objects must execute within their own transactions. When a new object is created, MTS automatically creates a new transaction for the object, regardless of whether its client has a transaction.

•	Supports transactions. This value indicates that the component's objects can execute within the scope of their client's transactions. When a new object is created, its object context inherits the transaction from the context of the client. If the client does not have a transaction, the new context is also created without one.

•	Does not support transactions. This value indicates that the component's objects do not run within the scope of transactions. When a new object is created, its object context is created without a transaction, regardless of whether the client has a transaction.

Most MTS components are declared as either Supports transactions or Requires a transaction. These values allow an object to execute within the scope of its client's transaction. You can see the difference between these values when an object is created from a context that does not have a transaction. If the component's transaction attribute is Supports transactions, the new object runs without a transaction. If it is declared as Requires a transaction, MTS automatically initiates a transaction for the new object.

Declaring a component as Requires a new transaction is similar to using Requires a transaction in that the component's objects are guaranteed to execute within transactions. However, when you declare the transaction attribute this way, an object never runs inside the scope of its client's transaction. Instead, the system always creates independent transactions for the new objects. For example, you can use this for auditing components that record work done on behalf of another transaction regardless of whether the original transaction commits or aborts.

Specifying Does not support transactions ensures that an object's context does not contain a transaction. This value is the default setting and is primarily used with versions of COM components that precede MTS.

Setting the Transaction Attribute

The transaction attribute is part of a component definition. The component developer determines it, and changes to it are not recommended.

You can set a transaction attribute at development time by:

•	Using values defined in Mtxattr.h. You can specify these values in an .odl file to encode them into the component's type library.

•	Using the MTS Explorer to create a package file for deploying your components.

Because Because Microsoft Visual Basic automatically generates a type library, Visual Basic developers must use the MTS Explorer to set the transaction attribute.

See Also

Application Components, Transactions


Enlisting Resources in Transactions

MTS provides automatic transactions, which means that transaction requirements are declared as component properties. MTS automatically begins transactions and commits or aborts these transactions on behalf of the component, based on the component's transaction property.

Automatic transactions work because resource dispensers pass transactions to the resource manager. For example, the ODBC Driver Manager is a resource dispenser for ODBC database connections. When a database connection is requested from a transactional component, the ODBC Driver Manager obtains the transaction from the object's context. The ODBC Driver Manager then associates (enlists) the database connection with the transaction.

If you do not have a resource dispenser, you can build your own using the Microsoft Transaction ServerSoftware Development Kit (SDK), which is located in the Microsoft Platform SDK. For more information, see the Resource Dispenser Guide and the samples included with the MTS SDK.

For a resource manager to participate in an MTS transaction, it must support one of the following protocols:

•	OLE Transactions

•	The X/Open DTP XA standard

OLE Transactions, the object-oriented, two-phase commit protocol defined by Microsoft, is the preferred protocol. OLE Transactions is based on the Component Object Model (COM) and is used by resource managers in order to participate in distributed transactions coordinated by Microsoft Distributed Transaction Coordinator (DTC). OLE Transactions is supported by Microsoft SQL Server version 6.5. For more information on supporting OLE Transactions, see the Resource Manager Guide and the samples included with the MTS SDK.

XA is the two-phase commit protocol defined by the X/Open DTP group. XA is natively supported by many Unix databases, including Informix, Oracle, and DB2.

For MTS to work with XA-compliant resource managers, an OLE Transactions-to-XA mapper, provided by the MTS SDK, makes it relatively straightforward for XA-compliant resource managers to provide resource dispensers that can accept OLE Transactions from MTS and translate to XA. For more information, see "Mapping OLE Transactions to the XA Protocol" in the MTS SDK, or contact your resource manager vendor.

See Also

Resource Dispensers, Transactions


Determining Transaction Outcome

This section discusses how applications determine whether a transaction will commit or abort.

First, it is important to understand that the MTS objects involved in a transaction do not need to know the transaction outcome. All objects involved in a transaction are automatically deactivated. Deactivation causes the objects to lose any state that they acquired during the transaction. Consequently, their behavior is not affected by the outcome of the transaction.

Each object can participate in determining the outcome of a transaction. Objects call SetComplete, SetAbort, EnableCommit, and DisableCommit, based on the desired component behavior. For example, an object would typically call SetAbort after receiving an error from a database operation, on a method call to another object, or due to a violation of a business rule such as an overdrawn account.

The client of the transaction determines its success or failure (commit or abort) based on values returned from the method call that caused the transaction to complete. The client can be either a base client or another MTS object that exists outside the transaction. The client must know which methods cause transactions to complete and how the method output values can be used to determine success (commit) or failure (abort).

An object method that intends to commit a transaction typically returns an HRESULT value of S_OK after calling SetComplete. On return, MTS automatically completes the transaction. If the transaction commits, the S_OK value is returned to the client. If it aborts, the HRESULT value is changed to CONTEXT_E_ABORTED. The client can use these two values to determine the outcome.

An object method typically notifies its client that it has forced the transaction to abort by calling SetAbort in one of two ways:

•	Return S_OK and use an output parameter to indicate the failure.

•	Return an HRESULT error code. Different codes could be used to distinguish different causes, or the generic CONTEXT_E_ABORTED error could be used.

For example, the Sample Bank application uses an output parameter to indicate failure:

Public Function Perform(lngPrimeAccount As Long, _

   lngSecondAccount As Long, lngAmount As Long, _

   strTranType As String, ByRef strResult As String) _

   As Long

' get our object context

Dim ctxObject As ObjectContext

Set ctxObject = GetObjectContext()

On Error GoTo ErrorHandler

' check for security

If (lngAmount > 500 Or lngAmount < -500) Then

    If Not ctxObject.IsCallerInRole("Managers") Then

        Err.Raise Number:=ERROR_NUMBER, _

        Description:="Need 'Managers' role " + _

           "for amounts over $500"

    End If

End If

.

.

.

ctxObject.SetComplete       ' we are finished and happy

Perform = 0

Exit Function

ErrorHandler:

ctxObject.SetAbort           ' we are unhappy

strResult = Err.Description  ' return the error message

Perform = -1           ' indicate that an error occured

End Function

It is also important to note that there are failure scenarios where the client cannot determine the transaction outcome. This situation results, for example, when a call failure occurs due to a transport error such as RPC_E_CONNECTION_TERMINATED). In such cases, it is necessary to use an application-defined protocol to determine the transaction outcome.

On clustered servers, MTS will not automatically reconnect to MS DTC in the event of a failover. Not enough information exists about the transaction composition and state to determine the appropriate course of action. Retries remain the responsibility of the client application. The client cannot differentiate an error caused by failover from other errors.

Resource managers are guaranteed to get transaction outcomes as part of the two-phase commit protocol managed by the Microsoft Distributed Transaction Coordinator. This feature allows resource managers to manage locks and to determine whether it is necessary to make state changes permanent or to discard them.


Transaction Server Objects
MTS Objects

An MTS object is an instance of an MTS component. MTS maintains context for each object. This context, which is implicitly associated with the object, contains information about the object's execution environment, such as the identity of the object's creator and, optionally, the transaction encompassing the work of the object. The object context is similar in concept to the process context that an operating system maintains for an executing program.

An MTS object and its associated context object

An MTS object and its associated context object have corresponding lifetimes. MTS creates the context before it creates the MTS object. MTS destroys the context after it destroys the MTS object.

See Also

Application Components, MTS Component Requirements, Context Objects, asconCreatingTransactionServerObjects, Passing Object References, Deactivating Objects


Context Objects

Each MTS object has an associated context object. A context object is an extensible MTS object that provides context for the execution of an instance, including transaction, activity, and security properties. When an MTS object is created, MTS automatically creates a context object for it. When the MTS object is released, MTS automatically releases the context object.

An MTS object and its associated context object

An MTS object's context has intrinsic properties that are determined during object creation. These properties include the identity of the client that initiated the object's creation and whether or not the object executes within the scope of a transaction.

The properties established for the new object context are determined by a combination of:

•	The transaction attributes of the component as specified in the MTS catalog.

•	The properties of the context from which the new object is created. For example, the client's context may contain a transaction.

If your application uses Microsoft Internet Information Server (IIS), you can retrieve IIS intrinsic objects as follows:

•	Using Visual Basic, by calling the Item method of the context object.

•	Using Microsoft Visual C++ or Microsoft Visual J++, by calling the GetProperty method of the IGetContextProperties interface.

For more information on IIS intrinsic objects, see the IIS documentation.

Contexts Are Implicit

MTS maintains an implicit relationship between an MTS object and its context. This feature eliminates the need for you to pass explicitly a context object through your application.

You can access an MTS object's context by calling the GetObjectContext function. This function returns a reference to the IObjectContext interface. Resource dispensers and other context-aware services can also access the object's context. This permits the ODBC resource dispenser automatically to enlist connections on the object's transaction.

Before a method of an MTS object is dispatched for execution, that object's context becomes the current context for the thread. This context remains current as long as the object remains within the context. Calling a method in a different context causes that context to become current; the caller's context is automatically restored on return from the method.

Managing References to the Context Object

You must not pass a reference to the context object outside the object. You must explicitly release every reference that you acquire on the object context.

The context object is not available during calls to the component's class factory. This means, for example, that a Visual C++ class implementation cannot access a context object during calls to a constructor or destructor. Objects that require access to the context object during initialization or destruction should implement IObjectControl. For more information, see Deactivating Objects.

See Also

MTS Objects, GetObjectContext, IObjectContext


Creating Transaction Server Objects
Creating MTS Objects

You can create MTS objects by:

•	Using context objects.

•	Using transaction context objects.

•	Using standard COM functions like CoCreateInstance or CreateObject.

Note   If you are using Visual C++ and running an MTS component in-process, you must:

•	Call CoInitialize(NULL) before requesting services from MTS or creating an MTS object.

•	Call CoInitializeSecurity to initialize process-specific security. MTS security is disabled when loading an MTS object in-process.

•	Call CoUninitialize only after you have finished using MTS or MTS objects, preferably just prior to terminating your application. You cannot call CoInitialize again and invoke more MTS services. Once CoUninitialize has been called, your application no longer executes in the MTS run-time environment.

Creating Objects Using a Context Object

You can create an MTS object by calling the CreateInstance method on the IObjectContext interface of an object's context object. The new MTS object's context inherits the activity, possibly a transaction, and all security identities from the creating object's context.

Creating an object using a context object

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.

Creating Objects Using a Transaction Context Object

If you want your base client to control transaction boundaries, use a transaction context object. You can create an MTS object by calling the CreateInstance method of the ITransactionContext interface. The new MTS object's context inherits the activity, possibly a transaction, and the identity of the initial client from the transaction context object. You can call the Commit method to commit an object's work and the Abort method to abort its work.

Creating an object using a transaction context object

Creating Objects Using CoCreateInstance

You can create MTS objects by using CoCreateInstance or any equivalent method based on CoGetClassObject and IClassFactory::CreateInstance. While this approach should suffice for many base client applications, there are some significant limitations for the client, including the inability to control transaction boundaries. Base clients that need this additional level of control can use a transaction context object.

Instantiating an object with CoCreateInstance

When you use CoGetClassObject with a component that is registered to run under MTS, it returns a reference to an MTS-provided class factory. This allows MTS to participate in the client's calls to IClassFactory::CreateInstance. The MTS class factory creates the context object and then calls the component's real class factory.

For clustered servers, if you are using the CoCreateInstanceEx function, use the name of the virtual server containing the MSDTC resource in the pwszName field of the COSERVERINFO structure. (See the Microsoft Platform SDK documentation for more details about CoCreateInstanceEx.)

Important It is recommended that you do not call CoCreateInstance to create MTS objects from within MTS objects. When you do so, the new object's context cannot inherit any properties from its client's context. In particular, the new object cannot execute within the scope of its client's transaction.

Aggregation

You cannot use an MTS object as part of an aggregate of other objects. CoCreateInstance returns CLASS_E_NOAGGREGATION to indicate an attempt to create an MTS object with another controlling IUnknown.

You can, however, create an MTS object that is implemented as an aggregation of objects.

Creating Objects Using Visual Basic

You can use the following object creation methods in Microsoft Visual Basic to create MTS objects:

•	The CreateObject function

•	The GetObject function

•	The New keyword (see the Important note for limitations)

•	Automatically if the object is an Application object

Using Visual Basic object creation methods results in the same limitations as using CoCreateInstance. To inherit a transaction from the creating object's context, use CreateInstance.

Important   Do not use the New operator, or a variable declared As New, to create an instance of a class that is part of the active project. In this situation, Visual Basic uses an implementation of object creation that does not use COM. To prevent this occurrence, it is recommended that you mark all objects passed out from a Visual Basic componentas Public Creatable, or its equivalent, and created with either the CreateObject function or the CreateInstance method of the ObjectContext object.

See Also

MTS Objects, Calling MTS Components, Context Objects, Passing Object References, Deactivating Objects, CreateInstance


Transaction Context Objects

The transaction context object allows base clients to combine the work of multiple MTS objects into a single transaction, without having to develop a new component specifically for that purpose.

The transaction context object's methods use its context object as follows:

•	CreateInstance — Calls CreateInstance and returns a reference to the newly created object.

•	Commit — Calls SetComplete and returns.

•	Abort — Calls SetAbort and returns.

The transaction context component is defined as Requires a New Transaction. You cannot use the transaction context object to enlist in an existing transaction.

For example, suppose you have two components, Walk and ChewGum. Each component is defined as Supports Transactions and calls SetComplete when it is finished with its work. A base client could compose the work done by each component in a single transaction.

Dim objTxCtx As TransactionContext

Dim objWalk As MyApp.Walk

Dim objChewGum As MyApp.ChewGum

' Get TransactionContext

Set objTxCtx = _

CreateObject("TxCtx.TransactionContext")

' Create instances of Walk and ChewGum

Set objWalk = _

objTxCtx.CreateInstance("MyApp.Walk")

Set objChewGum = _

objTxCtx.CreateInstance("MyApp.ChewGum")

' Both components do work

objWalk.Walk

objChewGum.ChewGum

' Commit the transaction

objTxCtx.Commit

Transaction Context Object Limitations

Note the following limitations when using a transaction context object:

•	Transaction composition

•	Location transparency

•	Base client does not have context

Transaction Composition

When using a transaction context object, the application logic that composes the work into a single transaction is tied to a specific base client implementation and the advantages of using MTS components are lost. These implementations include:

•	Ability to reuse the application logic as part of an even larger transaction

•	Imposition of declarative security

•	Flexibility to run the logic remotely from the client

Location Transparency

The transaction context object runs in-process with the base client, which means that MTS must exist on the base client computer. This may not be a problem, for example when the transaction context object is used from an Active Server Page (ASP) that is running on the same server as MTS.

Base Client Does Not Have Context

You do not get a context for the base client when you create a transaction context object. Transactional work can only be done indirectly, through MTS objects created by using the transaction context object. In particular, the base client cannot use MTS resource dispensers (such as ODBC) and have the work included in of the transaction. For example, developers may be familiar with the following syntax for doing transactional work on relational database systems:

BEGIN TRANSACTION

DoWork

COMMIT TRANSACTION

Using the transaction context object in a similar way does not yield the desired result:

Set objTxCtx = CreateObject("TxCtx.TransactionContext")

DoWork

objTxCtx.Commit

Set objTxCtx = Nothing

The call to DoWork in this example will not be enlisted in a transaction. You must build an MTS component that calls DoWork, create an object instance of that component using the transaction context object, then call that object from the base client in order for the work to be part of the client-controlled transaction.

See Also

Transactions, TransactionContext Object


Passing Parameters

This topic covers the following:

•	Parameter types and marshaling

•	Objects as parameters

•	Passing large data

Parameter Types and Marshaling

MTS object interfaces must be able to be marshaled. Marshaling interfaces allows calls across thread, process, and machine boundaries.

Standard COM marshaling is used. This means MTS object interfaces must either:

•	Have method parameters which are Automation data types and be described in a type library, or

•	Use custom interfaces with a MIDL-generated proxy-stub DLL.

For more information on type libraries and proxy-stub DLLs, see MTS Component Requirements.

Custom marshaling is not used. Even if a component supports the IMarshal interface, its IMarshal methods are never called by the MTS run-time environment.

VBScript Parameters

Components that are intended for use from Active Server Pages (ASPs) using Microsoft Visual Basicｮ Scripting Edition (VBScript) should support IDispatch and limit method parameter types as follows:

•	VBScript version 1.0--Any Automation type may be passed by value, but not by reference. Method return values must be of type Variant.

•	VBScript version 2.0--Same as VBScript version 1.0, except parameters of type Variant may now be passed by reference.

Objects as Parameters

Whether an object is passed by value or by reference is not specified by the client, but is a characteristic of the object itself. Basic COM objects can either be passed by reference or by value, depending on their implementation. If the COM object uses standard marshaling, then it is passed by reference. COM objects can also implement IMarshal to copy data by value. MTS objects are always passed by reference.

Additionally, the function of the object affects how it should be passed as a parameter. When deciding whether to pass objects by value or by reference, it is useful to classify the objects as follows:

•	Recordset Objects--Encapsulate raw data, such an ADO recordset. Recordset objects are not registered as MTS objects.

•	Business Object--Encapsulate business logic; for example, an order-processing component. Business objects should be registered as MTS objects.

The following table describes when to pass recordset objects by value or by reference:

Pass Parameter	If	Client Requirements
By value	Data is relatively small	Recipient requires all data and can get data without reaccessing caller.
By reference	Data is relatively large	Recipient does not require all data and must reaccess caller, possibly many times.
Note   Whether data is "small" or "large" also depends on the speed of the connection. For example, if the component is accessed over a corporate intranet, a much larger recordset can be passed to the client in one call than in a call made by a client accessing the component on an Internet server over a modem.

Because business objects are MTS objects, they are always passed by reference.

Passing Large Data

When returning a large amount of data, consider using a Microsoft Active Data Objects (ADO) Recordset object. In particular, the Microsoft Advanced Data Connector (ADC) provides a recordset implementation that can be disconnected from the server and marshaled by value to the client.

The disconnected recordset moves state to the client, allowing server resources to be freed. The client can make changes to the recordset and reconnect to the server to submit updates. For more information on state, see Holding State in Objects.

Another method of packaging large amounts of data is to use safe arrays. For example, when using Microsoft Remote Data Objects (RDO), you can use the rdoResultSet.GetRows method to copy rows into an array, and then pass the array back to the client. This requires fewer calls and is more efficient than issuing MoveNext calls across the network for each row.


Passing Object References

You must ensure that MTS object references are only exchanged in the following ways:

•	Through return from an object creation interface, such as CoCreateInstance (or its equivalent), ITransactionContext::CreateInstance, or IObjectContext::CreateInstance.

•	Through a call to QueryInterface.

•	Through a method that has called SafeRef to obtain the object reference.

An object reference that is obtained in these ways is called a safe reference. MTS ensures that methods invoked using safe references execute within the correct context.

Using SafeRef to pass a reference to an object

Note   It is not safe to exchange references by any other means. In particular, do not pass interfaces outside the object by using global variables. These restrictions are similar to those imposed by COM for references passed between apartments.

Calls that use safe references always pass through the MTS run-time environment. This allows MTS to manage context switches and allows MTS objects to have lifetimes that are independent of client references. For more information, see Deactivating Objects.

Callbacks

It is possible to make callbacks to clients and to other MTS components. For example, you can have an object that creates another object. The creating object can pass a reference to itself to the created object; the created object can then use this reference to call the creating object.

If you choose to use callbacks, note the following restrictions:

•	Calling back to the base client or another package requires Access-level security on the client. Additionally, the client must be a DCOM server.

•	Intervening firewalls may block calls back to the client.

•	Work done on the callback executes in the environment of the object being called. It may be part of the same transaction, a different transaction, or no transaction.

•	The creating object must call SafeRef and pass the returned reference to the created object in order to call back to itself.

See Also

SafeRef


Deactivating Objects

MTS extends COM to allow object deactivation, even while client references are maintained. This makes server applications more scalable by allowing server resources to be used more efficiently.

MTS objects are initially created in the deactivated state. When a client invokes a method on an object that is in a deactivated state, MTS automatically activates the object. During activation, the object is put into its initial state.

Note   For Visual C++ developers, calls to QueryInterface, AddRef, or Release do not cause activation.

This ability for an object to be deactivated and reactivated while clients hold references to it is called just-in-time activation. From the client's perspective, only a single instance of the object exists from the time the client creates it to the time it is finally released. In actuality, it is possible that the object has been deactivated and reactivated many times.

Just-in-time activation

The context object exists for the entire lifetime of its MTS object, even across one or more deactivation and reactivation cycles.

Object deactivation allows clients to hold references for long periods of time with limited consumption of server resources. Consider, for example, a client application that spends 99 percent of its time between transactions. In this case, the MTS objects are activated less than 1 percent of the time.

When is an object deactivated?

An MTS object is deactivated when any of the following occurs:

•	The object requests deactivation.

An object can request deactivation by using the IObjectContext interface. You can use the SetComplete method to indicate that the object has successfully completed its work and that the internal object state doesn't need to be retained for the next call from the client. Similarly, SetAbort indicates that the object cannot successfully complete its work and that its state does not need to be retained.

You can develop stateless objects by using MTS objects that deactivate on return from every method.

•	A transaction is committed or aborted.

MTS does not allow an object to maintain private state that it acquired during a transaction. When an object's transaction is committed or aborted, the object is deactivated. Of these deactivated objects, the only ones that can continue to exist are the ones that have references from clients outside the transaction. Subsequent calls to these objects reactivate them and cause them to execute in the next transaction.

•	The last client releases the object.

This occurrence is listed here for completeness. The object is deactivated and never reactivated. The object's context is also released.

How are objects deactivated?

MTS deactivates an object by releasing all its references to the object. This causes properly developed components to destroy the object; this feature also requires the component to follow the MTS reference passing rules (see Passing Object References) and the COM reference counting rules.

Note   MTS writes an Informational message to the event log when objects that do not report their reference count are deactivated.

Application components are responsible for releasing object resources on deactivation. This includes:

•	Resources that are allocated with MTS resource dispensers, such as ODBC database connections.

•	All other resources, including references to other objects (including MTS objects and context objects) and memory held by any instances of the component, such as using delete this in C++).

Doing Additional Work on Activation and Deactivation

If an object is not already activated and it supports IObjectControl, MTS calls the Activate method prior to initiating the client request. Components can use the Activate method to initialize objects. This is especially important for initialization that requires access to the context object. Here, keep in mind that the context is not available during calls to the component's class factory. Having access to the context object through Activate allows you to pass a reference to the context object to other methods; this reference can then be released in the Deactivate method. The Activate method is also useful for objects that support pooling (see Object Pooling and Recycling).

For objects that support the IObjectControl interface, MTS calls the Deactivate method when it deactivates the object. You can use this method to free resources held by the object. The Deactivate method is also useful for objects that support pooling. Like the Activate method, the Deactivate method has access to the object context.

See Also

Building Scalable Components, Stateful Components, Object Pooling and Recycling, SetComplete, SetAbort, IObjectControl


Object Pooling and Recycling

Objects that support the IObjectControl interface can participate in object recycling and pooling, which can increase the efficiency of activation and deactivation. After MTS calls the Deactivate method, it calls the CanBePooled method, allowing the object to be pooled for reuse. If the object returns TRUE, the object is added to the object pool. Objects that return FALSE or that do notsupport the IObjectControl interface are destroyed.

On activation, MTS uses an object from the pool if one is available. Only if the pool is empty will it use the component's class factory to create a new object.

Components that support object pooling must ensure that an object activated using an object from the pool is indistinguishable to the client from an object that is activated by creating a new object. Component developers must provide the appropriate code in the Activate and Deactivate method implementations to ensure this behavior.

The following table summarizes MTS run-time actions for client call processing.

	IObjectControl implemented by component
	No	Yes
Step 1 Activate the object if needed (just-in-time activation).	Use the component class factory to create an object.	Allocate an object from the pool. If pooling is not supported or the pool is empty, then use the component class factory to create an object.
		Call the object's Activate method.
Step 2 Execute the call.	Call the object method.	Call the object method.
Step 3 Deactivate the object if requested (SetComplete or SetAbort called before return).		Call object's Deactivate method
	Release the last reference held by the MTS run-time environment.	If the system supports pooling, then call CanBePooled. If it returns TRUE, then add the object to the pool. Otherwise, release the last reference held by the MTS run-time environment.
Important   Object pooling and recycling is not available in this release. MTS calls CanBePooled as described here, but no pooling takes place. This forward-compatibility encourages developers to use CanBePooled in their applications now in order to benefit from a future release without having to modify their applications later.

See Also

Deactivating Objects, IObjectControl


Transaction Server Clients
MTS Clients

An application or object that uses an MTS object is referred to as a client of the object. It is important to understand that this is a relative term, and describes a relationship with a specific object. For example, when MTS object A uses MTS object B, the object A, while still an object, is also a client.

Clients that run outside the direct control of the MTS run-time environment are referred to as base clients.

Clients and base clients: The Order object is a client of the Payment object

See Also

Base Clients, Base Clients vs. MTS Components


Base Clients

Base clients are the primary consumers of MTS objects, although base clients execute outside of the MTS run-time environment. One common role of a base client is to provide the application's user interface, and to map the end-user's requests to the business functions exposed by the MTS components.

You can create base clients with a variety of programming languages, including Microsoft Visual C++, Microsoft Visual Basic, Microsoft Visual J++, COBOL, and even Transact SQL. Base client programs can execute in a variety of environments, from application processes to general system services such as Microsoft Internet Information Server (IIS) or SQL Server. In fact, you can use any programming environment in which you can create COM objects and invoke methods on them.

See Also

MTS Clients, Base Clients vs. MTS Components


Base Clients vs. Transaction Server Components
Base Clients vs. MTS Components

The following table contrasts MTS components with base client applications.

MTS components	Base clients
MTS components are contained in COM dynamic-link libraries (DLLs); MTS loads DLLs into processes on demand.	Base clients can be written as executable files (.exe) or dynamic-link libraries (.dll); MTS is not involved in their initiation or loading.
MTS manages server processes that host MTS components.	MTS does not manage base client processes.
MTS creates and manages the threads used by components.	MTS does not create or manage the threads used by base client applications.
Every MTS object has an associated context object. MTS automatically creates, manages, and releases context objects.	Base clients do not have implicit context objects. They can use transaction context objects, but they must explicitly create, manage, and release them.
MTS objects can use resource dispensers. Resource dispensers have access to the context object, allowing acquired resources to be automatically associated with the context.	Base clients cannot use resource dispensers.
See Also

MTS Clients, Application Components


Activities

An activity is a set of objects executing on behalf of a base client application. Every MTS object belongs to one activity. This is an intrinsic property of the object and is recorded in the object's context. The association between an object and an activity cannot be changed. An activity includes the MTS object created by the base client, as well as any MTS objects created by that object and its descendants. These objects can be distributed across one or more processes, executing on one or more computers.

For example, an online banking application may have an MTS object dispatch credit and debit requests to various accounts, each represented by a different object. This dispatch object may use other objects as well, such as a receipt object to record the transaction. This results in several MTS objects that are either directly or indirectly under the control of the base client. These objects all belong to the same activity.

MTS tracks the flow of execution through each activity, preventing inadvertent parallelism from corrupting the application state. This feature results in a single logical thread of execution throughout a potentially distributed collection of objects. By having one logical thread, applications are significantly easier to write.

Whenever you use CoCreateInstance or its equivalent to create an MTS object, a new activity is created; note that this includes a base client creating a transaction context object.

When an MTS object is created from an existing context, using either a transaction context object or an MTS object context, the new object becomes a member of the same activity. In other words, the new context inherits the activity identifier of the context used to create it.

MTS only allows a single logical thread of execution within an activity. This is similar in behavior to a COM apartment, except that the objects can be distributed across multiple processes. When a base client calls into an activity, all other requests for work in the activity (such as from another client thread) are blocked until after the initial thread of execution returns back to the client.

Callbacks and Reentrancy

While MTS does not allow multiple threads of execution within an MTS object, reentrancy is possible via callbacks. Suppose you have an object that creates another object. If the creating object passes a reference to itself to the created object, either directly or indirectly, cycles can occur in the call graph. MTS objects that do this must be prepared to receive a method invocation while blocked waiting for a call to complete. MTS ensures that the incoming call belongs to the same logical thread by using the COM logical thread identifier. COM uses the logical thread identifier for a similar purpose in apartment objects.

Limitation

While no parallel execution can exist within the activity on any individual computer, the MTS run-time environment does not protect against clients entering into the same activity through objects on two different computers. This can result in two parallel threads of execution on different computers. However, if the thread of execution on one computer calls an object in the same activity on the other, the call will be blocked.

This behavior is based on the belief that the cost outweighs the benefits of providing fully distributed activity protection, both in terms of development and run-time performance.

See Also

Components and Threading, Passing Object References


Components and Threading

The MTS run-time environment manages threads for you. MTS components need not, and, in fact, should not, create threads. Components must never terminate a thread that calls into a DLL.

Every MTS component has a ThreadingModel Registry attribute, which you can specify when you develop the component. This attribute determines how the component's objects are assigned to threads for method execution. You can view the threading-model attribute in the MTS Explorer by clicking the Property view in the Components folder. The possible values are Single, Apartment, and Both.

Single-Threaded Components

All objects of a single-threaded component execute on the main thread. This is compatible with the default COM threading model, which is used for components that do not have a ThreadingModel Registry attribute.

The main threading model provides compatibility with COM components that are not reentrant. Because objects always execute on the main thread, method execution is serialized across all objects in the component. In fact, method execution is serialized across all components in a process that uses this policy. This allows components to use libraries that are not reentrant, but it has very limited scalability.

Limitations for Single-Threaded Components

Single-threaded, stateful components are prone to deadlocks. You can eliminate this problem by using stateless objects and calling SetComplete before returning from any method.

The following scenario describes how such a deadlock can occur. Suppose you have a single-threaded Account component, which is written to be both transactional and stateful. The following scenario describes how two clients, Client 1 and Client 2, could call objects in a way that causes an application deadlock:

•	Client 1 creates Account object A and calls it to update an account record. The database update is done under object A's transaction (Transaction 1). Because the object does not call SetComplete before returning to the client, Transaction 1 remains active.

•	Next, Client 2 creates Account object B and calls it to update the same account. Because its work is done under a different transaction (Transaction 2), the attempt to update the account record will block while waiting for Transaction 1 to complete.

•	Client 1 makes another call to object A, for instance, to have it make another change to the account record and complete the transaction. However, the call must wait for the main thread, which is still busy servicing the call from Client 2.

•	The two clients are now deadlocked. Client 1 holds a lock on the account record, while waiting for the server's main thread so that it can complete Transaction 1. Client 2 holds the server's main thread, while waiting for Transaction 1 to complete so that it can update the account record.

Note that this is not a deadlock from the SQL perspective because A's and B's connections are in different transactions.

Apartment-Threaded Components

Each object of an apartment-threaded component is assigned to a thread its apartment, for the life of the object; however, multiple threads  can be used for multiple objects. This is a standard COM concurrency model. Each apartment is tied to a specific thread and has a Windows message pump.

The apartment threading model provides significant concurrency improvements over the main threading model. Activities determine apartment boundaries; two objects can execute concurrently as long as they are in different activities. These objects may be in the same component or in different components.

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.

See Also

Activities


Programmatic Security

The MTS security model consists of declarative security and programmatic security. Developers can build both declarative and programmatic security into their components prior to deploying them on a Windows NT security domain.

Important   Security is not supported on Windows 98. Note the following application behavior when running MTS on Windows 98:

•	All identities are mapped to "Windows 98".

•	Role configuration is not supported.

•	Checking roles always return success.

Roles are central to the MTS security model. A role is an abstraction that defines a logical group of users. At development time, you use roles to define declarative authorization and programmatic security logic. At deployment time, you bind these roles to specific groups and users.

You can administer package security with the MTS Explorer. This is a form of declarative security, which does no't require any component programming is based on standard Windows NT security.

MTS also allows component applications to implement additional access control programmatically. MTS security is integrated with DCOM and Windows NT security. See the Microsoft Platform SDK for further information on COM security.

See Also

Basic Security Methods, Advanced Security Methods


Basic Security Methods

The IObjectContext interface provides two methods for basic programmatic security:

•	IsCallerInRole

•	IsSecurityEnabled

The key to understanding how MTS security works is to understand roles, as discussed in the following sections.

Roles from a Development Perspective

A role is a symbolic name that defines a logical group of users for a package of components. For example, an online banking application might define roles for Manager and Teller.

You can define authorization for each component and component interface by assigning roles. For example, in the online banking application, only the Manager may be authorized to perform bank transactions above a certain amount of money.

Roles are defined during application development. These roles are then assigned to specific users at deployment time.

Important   Roles on a dual interface are not enforced when IDispatch (late-binding) is used.

Checking If a Caller Is in a Role

The IsCallerInRole method determines if a caller is assigned to a role. The caller is the direct caller, which is the identity of the process (base client or server process) calling into the current server process.

The following illustration shows an application used to order supplies for a business.

You can use roles to determine whether the base client has access to objects in the server process. In this scenario, the server process would check to see if the base client is allowed to place an order. Calling IsCallerInRole on the Order object context checks if the direct caller, which is in this case the base client, is in a given role. Such a role might be Purchaser, to restrict the placing of orders to employees within that role.

Security checks are made when a process boundary is crossed. If the Payment object accesses a database, the access rights to the database are derived from the identity of the server process, not the base client. The database would use its own proprietary authorization checking.

Server-process security does not use impersonation. IsCallerInRole has the same semantics regardless of how many calls have taken place within the server process. The identity of the direct caller is always used to make the check. For more information on impersonation, see Advanced Security Methods.

Security for In-Process Components

Because the level of trust is process-wide, running MTS components in-process is not recommended for secure applications. Access checks are not made on calls between components in the same server process. Configuring MTS components to run in-process with the base client gives the base client access to all components within that server process.

The IsSecurityEnabled method determines if security checking is enabled. This method returns FALSE when running in-process. IsSecurityEnabled can be a useful check to make before using IsCallerInRole. IsCallerInRole will always return TRUE when called on an object that is running in-process, which may have unintended effects.

When an MTS component is part of a Library package (in-process), it effectively becomes part of the hosting Server package that creates it. If you create Library packages with components that call IsCallerInRole, you should instruct installers of your Library packages to define the Library package's roles on the hosting Server package. Otherwise, IsCallerInRole will always fail.

See Also

IsCallerInRole, IsSecurityEnabled, Secured Components


Advanced Security Methods

MTS objects can use the ISecurityProperty interface to obtain security-related information from the object context, including the identity of the client that created the object, as well as the identity of the current calling client. Applications can use this information to implement custom access control, such as using the Win32 security interfaces.

Note   Visual Basic programmers can use the SecurityProperty object. The methods for SecurityProperty return user name strings instead of security identifiers (SIDs).

Security Identifiers (SIDs)

A Windows NT security identifier (SID) is a unique value that identifies a user or group. You can use SIDs to determine the exact identity of a user. Because of their uniqueness, SIDs do not have the flexibility of roles.

Callers and Creators

The following figure shows which SIDs are returned by the various methods on ISecurityProperty after a certain sequence of method calls.

Calling the following methods on Object Y returns SIDs associated with these users:

•	GetDirectCallerSID returns the SID associated with User B.

•	GetDirectCreatorSID returns the SID associated with User B.

•	GetOriginalCallerSID returns the SID associated with User D.

•	GetOriginalCreatorSID returns the SID associated with User A.

Impersonation

Impersonation allows a thread to execute in a security context different from that of the process that owns the thread. Consider the following application scenario.

Basic Security Methods described an order-entry scenario in which the base client represents an employee submitting an order. In this scenario, the client is not authorized to use the Payment object and its associated database directly.

Suppose the base client were a report writer for an accounting program. In this case, you want to allow access to the Payment object's database. One way to accomplish this is for the Order object to impersonate the base client, allowing the database to use its own security checking to determine access privileges.

MTS does not promote the use of impersonation, but encourages role-based security. Security is simplified by the single-level of authorization provided by MTS, whereas the impersonation model has an n-level authorization architecture. The report-writer scenario can be simplified by defining a role, such as Accountant, to allow access to the database.


Error Handling

Fault Isolation and Failfast

MTS performs extensive internal integrity and consistency checks. If MTS encounters an unexpected internal error condition, it immediately terminates the process. This policy, called failfast, facilitates fault containment and results in more reliable and robust systems.

Consider a case in which MTS detects that one of its data structures is in a corrupted state. At this point, both the cause and the magnitude of the corruption are unknown. Unfortunately, MTS cannot tell how far the damage has spread. Certainly MTS is in an indeterminate state. But it does not run in isolation. Like other DLLs, it is hosted in a process environment and shares a single address space with the main program executable and many other DLLs. Consequently, it is safe to assume that the entire process has been corrupted. The process is immediately terminated to prevent it from spreading potentially corrupted information to other processes or, worse yet, from allowing corrupted data to be committed and made durable.

As a developer or administrator, you should inspect the Windows NT Event Viewer Application Log for details on any failfast or serious application errors.

Exceptions in MTS Objects

MTS does not allow exceptions to propagate outside of a context. If an exception occurs while executing within an MTS context and the application doesn't catch the exception before returning from the context, MTS catches the exception and terminates the process. Using the failfast policy in this case is based on the assumption that the exception has put the process into an indeterminate state--it is not safe to continue processing.

MTS Object Method Error Return Codes

MTS never changes the value of an HRESULT error code, such as E_UNEXPECTED or E_FAIL, returned by an MTS object method.

When an MTS object returns an HRESULT status code, such as S_OK or S_FALSE, MTS may convert the status code into an MTS error code before it returns to the caller. This occurs, for example, when the application returns S_OK after calling SetComplete; if the object is the root of an automatic transaction that fails to commit, the HRESULT is converted to CONTEXT_E_ABORTED.

When MTS converts a status code to an error code, it clears all of the method's output parameters. Returned references are released and the values of the returned object pointers are set to NULL.

See Also

MTS Error Diagnosis, MTS Error Codes


Developing Applications for Microsoft Transaction Server with Visual Basic
Developing Applications for MTS

Building MTS Applications

Explains the key concepts that a component application developer needs to understand for developing Microsoft Transaction Server (MTS) applications.

Creating a Simple ActiveX Component

Demonstrates how to create a component and register the component in the Microsoft Transaction Server run-time environment.

Building Scalable Components

Demonstrates how to use just-in-time activation to use server resources efficiently, resulting in more scalable applications and improved performance.

Building Transactional Components

Introduces transactional components and the benefits of running components within the same transaction.

Sharing State

Demonstrates how to use the Shared Property Manager to share state among multiple Transaction Server objects running in the same process.

Stateful Components

Discusses stateful components and outlines some of the issues associated with writing stateful application components.

Multiple Transactions

Explains the benefits of distributing work among multiple transactions.

Secured Components

Shows how to use Microsoft Transaction Server's security features to restrict the use of application features to designated users.


Building MTS Applications

This topic contains information that a component application developer needs to understand before building Microsoft Transaction Server (MTS) applications.

MTS Component Requirements

Business Logic in MTS Components

Packaging MTS Components

Calling MTS Components

Holding State in Objects

Database Access Interfaces with MTS

Developing MTS Components with Java

Debugging MTS Components

Automating MTS Deployment

MTS Error Diagnosis


Transaction Server Component Requirements
MTS Component Requirements

An MTS component is a type of COM component that executes in the MTS run-time environment. In addition to the COM requirements, MTS requires that the component must be a dynamic-link library (DLL). Components that are implemented as executable files (.exe files) cannot execute in the MTS run-time environment. For example, if you build a Remote Automation server executable file with Microsoft Visual Basic, you must rebuild it as a DLL.

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

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.

Additional Requirements for Visual C++ Components

•	The component must have a standard class factory.

The component DLL must implement and export the standard DllGetClassObject function and support the IClassFactory interface. MTS uses this interface to create objects. IClassFactory::CreateInstance must return a unique instance of an MTS object.

•	The component must only export interfaces that use standard marshaling. For more information, see Passing Parameters.

•	All component interfaces and coclasses must be described by a type library. The information in the type library is used by the MTS Explorer to extract information about the installed components.

•	For custom interfaces that cannot be marshaled using standard Automation support, you must build the proxy-stub DLL with MIDL version 3.00.44 or later (provided with in the Microsoft Platform SDK for Windows NT version 4.0); use the  -Oicf and  /MD compiler options; and link the DLL with the mtxih.lib, LE32.lib, and ADVAPI32.lib  libraries provided by MTS. The mtxih.lib library must be the first file that you link into your proxy-stub DLL. If the component has both a type library and a proxy-stub DLL, MTS will use the proxy-stub DLL.

•	The component must export the DllRegisterServer function and perform self-registration of its CLSID, ProgID, interfaces, and type library in this routine.

Development tools such as Visual Basic and the Active Template Library, which is available with Microsoft Visual C++, allow you to generate interfaces that COM can marshal automatically. These interfaces, known as dual interfaces, are derived from IDispatch and use the built-in Automation marshaling support.

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.

Registering MTS Components

You manage MTS components by using the MTS Explorer. Before a component can run with context in the MTS run-time environment, you must use the MTS Explorer to define the component in the MTS catalog. In addition to keeping track of a component's basic COM attributes, such as the name of the implementation DLL, the MTS catalog maintains a set of MTS-specific attributes. MTS uses these attributes to provide capabilities in addition to those provided by COM. For example, the transaction attribute controls the transactional characteristics of a component.

The MTS Explorer assigns components to a package that controls the assignment of components to server processes and control client access to components.

Note   MTS allows only a single server process associated with a given package to run on a computer at a time. MTS writes a warning event message to the log if you attempt to start a second instance of an already active package. However, COM does not explicitly disallow multiple servers running the same COM classes. MTS writes a warning message to the log in the event that two threads try to start the package at the same time. This event is especially likely on a symmetric multiprocessing (SMP) computer where the two package invocations are concurrent. In these cases, MTS enforces a rule of one server process for each package by terminating one of the extra packages. COM then connects to the one server process still running and successfully returns.

Registration for Components Developed with Visual Basic

Whenever you recompile a COM DLL (or "ActiveX DLL") project in Visual Basic, 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, 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 works with Visual Basic versions 4.0, 5.0 and 6.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 Binary Compatibility setting in the Visual Basic Project Properties 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, 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 without selecting theBinary Compatibility 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.

Running COM Components Under MTS

Exercise caution when registering a standard COM component (one developed without regard to MTS) to execute under MTS control.

First, ensure that references are safely passed between contexts (see Passing Object References).

Second, if the component uses other components, consider running them under MTS. Rewrite the code for creating objects in these components to use CreateInstance (see Creating MTS Objects).

Third, you can effectively use automatic transactions only with components that indicate the completion of their work by calling either the SetComplete or SetAbort methods. If a component does not use these methods, an automatic transaction can only be completed when the client releases the object. MTS will attempt to commit the transaction, but there is no way for the client to determine whether the transaction has been committed or aborted. Therefore, it is recommended that you do not register components as Requires a transaction or Requires a new transaction unless they use SetComplete and SetAbort.

Including Multiple Components in DLLs

You can implement multiple components in the same DLL. The MTS Explorer allows components from the same DLL to be installed in separate packages.

Including Type Libraries and Proxy-Stub DLLs in MTS Components

Development tools supporting ActiveX components can merge your type library or proxy-stub DLL with your implementation DLL. If you do not want to distribute your implementation DLL to client computers, keep your type libraries and proxy-stub DLLs separate from your implementation DLLs. The client only needs a type library or custom proxy-stub DLL to use your server application remotely.


Business Logic in MTS Components

This topic describes how to enact business logic in MTS components.

Granularity is determined by the number of tasks performed by a component. The granularity of a component affects the performance, debugging, and reusability of your MTS components. A fine-grained component performs a single task, such as calculating tax on a sales order. Fine-grained components consume and release resources quickly after completing a task. A component that enacts a single business rule can facilitate testing packages, because isolating individual tasks in components makes testing your applications easier. In addition, fine-grained components are easily reused in other packages. In the following example, a component performs a single task: adding a customer record to the database.

Function Update(ByVal strEmail As String, _

ByVal bNewCust As Boolean, ByVal strContact As String,_

ByVal strPhoneNumber As String, _

ByVal strNightPhoneNumber As String)

    Dim ctxObject As ObjectContext

    Set ctxObject = GetObjectContext

    On Error GoTo ErrorHandler

' Code accesses the customer row from the database.

' Customer information is updated with information

' that was passed in.

'

    ctxObject.SetComplete

    Exit Function

This simple component uses system resources efficiently (passing parameters by value), is easy to debug (single function), and also reusable in any other application that maintains customer data.

A coarse-grained component performs multiple tasks. Coarse-grained components are generally harder to debug and reuse in applications. For example, a PlaceOrder component might add a new order, update inventory, and update customer information. PlaceOrder is a more coarsely grained component because it performs more "work" by adding, updating, and deleting customer, inventory and order information.

For more information about components' shared resources, see Holding State in Objects.


Packaging MTS Components

This document describes how you should package your MTS components. Consider the following design issues when defining package boundaries:

•	Activation

•	Shared resources

•	Fault isolation

•	Security isolation

Activation

You can select either of the following Activation levels for your packages:

•	Library (running within the same process as the client that creates the object)

•	Server (on the same computer but in a different process)

MTS provides a way to set up remote components by using the Remote Computer and Remote Component folders in the MTS Explorer hierarchy. For more information about "pulling" or "pushing" components between computers, see the Administrator's Guide.

By default, components run in a server process on the local computer. If you run your components within the MTS server process, you enable resource sharing, security, and easier administration by using the MTS Explorer for your component. Running components in-process provides an immediate performance benefit, because you do not have to marshal parameters cross-process. However, in-process components do not support declarative security and you lose fault isolation.

Sidebar: In-process Components and Security

Note that in-process components do not support declarative security or offer the benefits of process isolation. In-process components will run in any process that creates the component. Role checking is disabled between in-process components because IsCallerInRole returns True. In other words, the direct caller always passes the authorization check.

Also, it is recommended that you place your components as close as possible to the data source. If you are building a distributed application with a number of packages running on local and remote servers, try to group your components according to the location of your data. For example, in the following figure, the Accounting server hosts an Accounting package and Accounting database.

Shared Resources

Sharing resources in a multiuser environment results in faster applications that scale more easily. Note that only components marked with the Local activation setting can share resources. Package your components to take advantage of the resource sharing and pooling that MTS provides for your application.

Pool your resources by server process.Note that MTS runs each hosted package in a separate server process. The fewer pools you have running on your server, the more efficiently you pool resources, so  try to group components that share "expensive" resources, such as connections to a specific database. If you reuse the expensive resources within your package, you can greatly improve the performance and scaling of your application. For example, if you have a database lookup and a database update component running in a customer maintenance application, package those components together so that they can share database connections.

Fault Isolation

Fault isolation requires separating components into packages that can operate in their own server process. Components in the same package share the same server process if all the activation settings are the same. By placing components in separate packages, you can mitigate the impact of a component failure because each package runs in a separate server process.

You can also use fault isolation to test new components. You can stage updates to MTS applications by introducing new components. Fault isolation for packages greatly reduces the risk of your local server package failing when you introduce a new component to a shared environment.

Security Isolation

MTS security roles represent a logical group of user accounts which are mapped to Microsoft Windows NTｮ domain users and groups during the deployment of the package. You can use the MTS Explorer to define declarative authorization checking by applying roles to components and component interfaces. Applying a security role to a component defines access privileges for any user assigned as a member of that security role. Users not assigned to a role with access privileges to a package cannot use the package. Because security authorization occurs between packages rather than between components within a package, it is recommended that you consider the MTS security model when determining your package boundaries. Note that security isolation only applies to packages with components running under the Server activation setting.

Security authorization is checked when a method call crosses a package boundary, such as when a client calls into a package or one package calls another. When you package your components, make sure you group components that can safely call each other without requiring security checks within one package.

All components within a package run under the identity established for the package. If you run under different identities, separate them into two different packages.

You can use declarative security between the client and server, and database security based on package identity between the server and data source. You can restrict access to a data source by assigning an identity to a package, and configuring the database to accept updates according to package identity.

If you use package identity to set up your database security, the database recognizes the package identity as a single user. If database access occurs under an identity set by the package, the database connection set up for the package identity name can be used by all the users mapped to role or roles for that package. This kind of resource sharing improves application performance and scalability.


Calling MTS Components

This topic covers the following:

•	Calling MTS Components using DCOM

•	Calling MTS Components from an Active Server Page

•	Calling MTS Components from a Web Browser-Resident Component

For more information on the methods for creating MTS objects, see Creating MTS Objects.

Calling MTS Components from a Client Application

MTS components can be located on a separate computer from the client. A client can call a remote MTS component using DCOM, HTTP, or Remote Automation. To run an MTS component on the client computer, the client computer must have MTS installed.

Calling MTS Components through DCOM

DCOM is the standard transport for calling MTS components. To enable DCOM calls to MTS components, you must configure the following:

Client Registry Settings -- The easiest way to configure your client application to call a remote MTS component is to use the application executable utility, which automatically configures client registry settings. For more information, see the Administrator's Guide.

DCOM Security Settings -- You may have to configure the Impersonation Level and Authentication Level on both client and server computers. MTS works properly using the default values for these settings: Identify for Impersonation Level and Connect for Authentication Level. Make the necessary changes in the MTS Explorer at the package level. Changing default settings by using the DCOM configuration utility (dcomcnfg.exe) is not recommended.

Windows 98 includes DCOM support. However, if you want to use Microsoft Windows 95 clients with MTS, install DCOM for Windowsｮ 95. For the latest information on DCOM support for Windows 95, see http://www.microsoft.com/oledev on the World Wide Web.

Calling MTS Components through Remote Automation

Remote Automation was introduced with Visual Basic version 4.0, before the introduction of DCOM. It is useful for 16-bit clients, because DCOM works only in 32-bit environments. To use Remote Automation with MTS, the Remote Automation Manager (RACMAN) must be running on the server where the MTS components are installed. For more information, see the Visual Basic documentation.

Note   You cannot use MTS security Remote Automation since all calls are made using the RACMAN identity. Because RACMAN does not impersonate when calling the components on the server, the client identity cannot be determined.

Calling MTS Components through HTTP

There are two ways a client can call an MTS component through HTTP:

•	Call an Active Server Page (ASP), which in turn calls the MTS component using DCOM.

•	Call the MTS component from a Web browser - resident component using the ActiveX Data Objects (ADO) Remote Data Service (RDS), which in turn uses HTTP. For more information about RDS, see http://www.microsoft.com/adc.

Calling MTS Components from an Active Server Page

You can call MTS components from Active Server Pages (ASPs). You can create an MTS object from an ASP by calling Server.CreateObject. Note that if the MTS component has implemented the OnStartPage and OnEndPage methods, the OnStartPage method is called at this time.

You can run your MTS components in-process with or out-of-process with Internet Information Server (IIS). If you run your MTS components in-process with IIS, be aware that if MTS encounters an unexpected internal error condition or an unhandled application error such as a general-protection fault inside a component method call, it immediately results in a failfast, thus terminating the process and IIS.

By default, IIS 3.0 disables calling out-of-process components. To enable calling out-of-process components, modify the following registry entry

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\ASP\Parameters

by setting the AllowOutOfProcCmpnts key to 1.

Calling MTS Components from a Web Browser-Resident Component

You can call an MTS component from a Web browser - resident component. Use the application executable utility to configure that client, and then use the HTML <OBJECT> tag to call that component. You can also use the <OBJECT> tag to create an MTS object in-process with the browser client. Remember that MTS must be installed on the client computer for an MTS component to run in-process.

The component should be made safe for scripting, either through a component category entry in the registry, or by supporting the IObjectSafety interface.

Remote Data Service (RDS) also allows you to create web browser - resident components using the <OBJECT> tag. RDS supports the following:

•	HTTP

•	HTTPS (HTTP over Secure Socket Layer)

•	DCOM

•	In-process server

Except for in-process objects, the CreateObject method of the DataSpace object creates a proxy for the MTS object that runs in a local or remote server process.

You must configure the following registry key to the Prog ID of the object that you want to call:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ADCLaunch


Holding State in Objects

Although there are many benefits to using stateless MTS objects, there are cases where holding state is desirable. This topic provides some guidelines in deciding where state is held in your application.

The following diagram shows a three-tier architecture:

Typically, the latency between tiers differs greatly. Calls between the presentation tier and business tier are often an order of magnitude slower than calls between the business tier and data tier. As a result, held state is more costly when calling into the business tier.

However, it often makes sense to hold state within the transaction boundary itself. For example, the objects in the data tier may represent a complex join across many tables in separate databases. Reconstructing the data object state is potentially more inefficient than the cost of the resources held by those objects while they remain active.

Since objects lose state on transaction boundaries, if you need to hold state across transactions, use the Shared Property Manager or store the state in a database.

Example: Order-Entry Application

There are two separate issues when considering the effects of holding state in an application:

•	Network roundtrips -- More frequent network roundtrips and slower connections extend the lifetime of the called MTS object.

•	Held resources -- Holding state often means holding onto a resource, such as a database connection, and potentially, locks on the database.

Consider the example of an online shopping application. The client chooses items from a catalog and submits an order. Order processing is handled by a business object, which in turn stores the order in a database (not shown).

One way of building the application is for the client to call an Order object, with each call adding or removing an item from the order:

This application has the following properties:

•	Client maintains no state.

•	Server maintains state across multiple calls.

•	Many network roundtrips.

•	High contention for resources. The database connection is held for the lifetime of the Order object. This is not a very scalable solution.

You can require that the client cache the items in an array or recordset:

This application has the following properties:

•	Stateful client.

•	Server is virtually stateless with one call to the server.

•	Fewer network roundtrips.

•	Less contention for resources. This is a scalable solution.

Concurrency

In addition to network bandwidth and resources, concurrency affects application performance. There are two types of concurrency:

•	Pessimistic -- As soon as editing begins, the database locks the records being changed. The records are unlocked when all changes are complete. No two users can access the same record at the same time.

•	Optimistic -- The database locks the records being changed only when the changes are committed. Two users can access the same record at the same time, and the database must be able to reconcile, or simply reject, changed records that have been edited by multiple users prior to commit.

Implementing a server cache implies optimistic concurrency. The server does not have to hold locks on the database, thus freeing resources.

However, if there is high contention for the resource, pessimistic concurrency may be preferred. It is easier to reject a request to access a database and have the server try again than it is to reconcile cached, out-of-date data with a rapidly changing database.


Database Access Interfaces with MTS

This topic describes the database access interface options for MTS applications. You can use the Open Database Connectivity (ODBC) Application Programming Interface (API) to access a resource manager (which is a system service that manages durable data), or a data access model that functions over the ODBC layer. Because the ODBC version 3.0 Driver Manager is an MTS resource dispenser, data accessed via ODBC is automatically protected by your object's transaction. For object transactions, an ODBC-compliant database must support the following:

•	The database's ODBC driver must be thread safe. It also must be able to connect to the driver from one thread, use the connection from another thread, and disconnect from another thread.

•	If ODBC is used from within a transactional component, then the ODBC driver must also support the SQL_ATTR_ENLIST_IN_DTC connection attribute. This is how the ODBC Driver Manager asks the ODBC driver to enlist a connection on a transaction. You can make your component transactional by setting the transaction property for your component in the MTS Explorer. If you are using a database without a resource dispenser that can recognize MTS transactions, contact your database vendor to obtain the required support.

The following table summarizes database requirements for full MTS support.

Requirements	Description	Resources (if applicable)
Support for the OLE transactions specification, or support for XA protocol	Enables direct interaction with Distributed Transaction Coordinator (DTC). Use the XA Mapper to interact with DTC	MTS SDK in the Microsoft Platform SDK.
ODBC driver	Platform requirement for MTS server components	ODBC version 3.0 SDK
ODBC driver support for the ODBC version 3.0 SetConnectAttr SQL_ATTR_ENLIST_ IN_DTC call.	MTS uses this call to pass the transaction identifier to the ODBC driver. The ODBC driver then passes the transaction identifier to the database engine.	ODBC version 3.0 SDK
Fully thread-safe ODBC driver	ODBC driver must be able to handle concurrent calls from any thread at any time.	ODBC version 3.0 SDK
ODBC driver must not require thread affinity	ODBC driver must be able to connect to the driver from one thread, use the connection from another thread, and disconnect from another thread.	ODBC version 3.0 SDK
If a memory access violation in the mtx.exe process occurs within the driver after 60 seconds of inactivity, you may be using an ODBC driver that is not thread safe or requires thread affinity. The fault occurs in the driver when the inactive connections are being disconnected.

MTS Distributed Transaction Coordinator

MTS uses the services of the Microsoft Distributed Transaction Coordinator (DTC) for transaction coordination. DTC is a system service that coordinates transactions that span multiple resource managers. Work can be committed as a single transaction, even if it spans multiple resource managers, potentially on separate computers. DTC was initially released as part of Microsoft SQL Server version 6.5, and is included as part of MTS. DTC implements a two-phase commit protocol that ensures that the transaction outcome (either commit or abort) is consistent across all resource managers involved in a transaction. DTC supports resource managers that implement OLE Transactions, X/Open XA protocols, and LU 6.2 Sync Level 2.

Choosing your Data Access Model

The following table summarizes commonly used data access models supported by MTS.

Interface	Description
Microsoft ActiveX Data Objects (ADO), Remote Data Service (RDS)	ADO offers one common yet extensible programming model for accessing data. ADO includes the ability to pass query results (Recordsets) between server and client, and the ability to pass updated Recordsets from client to server using RDS.
OLE DB	OLE DB is a low-level interface that provides uniform access to any tabular data source. You cannot call OLE DB interfaces directly from Microsoftｮ Visual Basicｮ because OLE DB is a pointer-based interface. A Visual Basic client can access an OLE DB data source through ADO.
Open DataBase Connectivity (ODBC)	ODBC is a recognized standard interface to relational data sources. ODBC is fast and provides a universal interface that is not optimized for any specific data source.
Remote Data Objects (RDO)	RDO is a thin object layer interface to the ODBC API. It is specifically designed to access remote ODBC relational data sources.  Note that adding the rdExecDirect flag to the .Execute method ensures that a temporaray stored procedure is not created when using two DSN's from the same transaction. See the RDO documentation for more details.
The diagram below illustrates how MTS components interact with the different data access interfaces:

ADO is not specifically designed for relational or ISAM databases, but as an object interface to any data source. ADO can access relational databases, ISAM, text, hierarchical, or any type of data source, as long as a data access provider exists. ADO is built around a set of core functions that all data sources are expected to implement. ADO can access native OLE DB data sources, including a specific OLE DB provider that provides access to ODBC drivers. ADO ships with the OLE DB Software Development Kit (SDK).

RDO does have some functionality that is not currently implemented in ADO, including the following:

•	Events on the Engine, Connection, Resultset, and Column objects

•	Asynchronous operations

•	Queries as methods

•	Enhanced batch-mode error and contingency handling

•	Tight integration with Visual Basic, as in the Query Connection designer and TSQL debugger.

Future versions of ADO will provide a superset of RDO version 2.0 functionality and provide a far more sophisticated interface, in addition to an easier programming model. Because ADO is an Automation-based component, any application or language capable of working with Automation objects can use it.


Developing MTS Components with Java

You can develop Java MTS components using tools provided by MTS and Visual J++. It is also recommended that you install the latest version of the Microsoft SDK for Java, available at http://www.microsoft.com/java.

This section contains the following topics:

•	Using Visual J++ 6.0

•	Using the Microsoft SDK for Java

•	Using an MTS Component from Java

•	Using the Java Sample Bank Components

Using Visual J++ 6.0

If you are using Microsoft Visual J++, not only can you create MTS components completely within the integrated development environment (IDE), but the steps required to build a component for MTS are greatly simplified over earlier versions of Visual J++.

Because Visual J++ 6.0 has many new features to support building and debugging components for MTS, some of the steps in the following sections do not apply to Visual J++ 6.0. For more information about building an MTS component in Visual J++ 6.0, see the Visual J++ 6.0 documentation.

Using the Microsoft SDK for Java

Note   The following steps assume you are using the Microsoft SDK for Java along with Visual J++ 1.0 or 1.1. (If you have Visual J++ 6.0, these steps are not necessary. For more information, see the Visual J++ 6.0 documentation.)

To implement a component in Java, follow these steps

1	Run the ActiveX Wizard for Java (available with Visual J++) for each Java class file to create an IDL file. Follow the instructions when the wizard asks you to modify your class declaration.

2	Modify the IDL files to add JAVACLASS and PROGID to the coclass attributes. For more information, see Using IDL Files with Java Components.

3	Run the ActiveX Component Wizard for Java again. Use the IDL files that you created in Step 1 to create type libraries for your components.

This will create a set of Java class files, typically under \%systemroot%\Java\Trustlib. It will create one class file for each custom interface, and one class file for each coclass in the library.

4	Run JAVAGUID against each class file generated in Step 3. For more information, see Working with GUIDs in Java.

5	Recompile your Java implementation classes.

6	Run EXEGEN to convert the type libraries and class files into a DLL. For more information, see Using EXEGEN to Create DLLs.

7	Use the MTS Explorer to install the DLL.

Using IDL Files with Java Components

To specify the custom attributes in a type library, add the following in your IDL or ODL file:

#include <JavaAttr.h>

Within the attributes section of a coclass, specify the JAVACLASS:

JAVACLASS("package.class")

You may optionally specify a PROGID:

PROGID("Progid")

For example:

[

uuid(a2cda060-2d38-11d0-b94b-0080c7394688),

helpstring("Account Class"),

JAVACLASS("Account.AccountObj"),

PROGID("Bank.Account.VJ"),

TRANSACTION_REQUIRED

]

coclass CAccount

{

[default] interface IAccount;

};

Using EXEGEN to Create DLLs

EXEGEN is the Java executable file generator. To use this file, copy it to the appropriate destination folders (usually \JavaSDK\bin). This version of EXEGEN.EXE is capable of creating DLL files from Java classes, and can also include user-specified resources in its output files. This version of EXEGEN no longer supports the /base: directive. Class files are always included with the proper name. It supports a new /D directive that causes it to generate a DLL file instead of an EXE.

EXEGEN is now capable of reading five types of input files:

•	Java class files

•	RES files containg resources to be included

•	Executable files containg resources to be included

•	TLB files containing type libraries to be included

•	Text files describing which classes should be registered (DLL only).

If you use EXEGEN to create a DLL, the DLL can self-register any included Java classes that implement COM objects. There are two ways to tell EXEGEN which classes should be registered:

•	Include a type library that contains custom attributes for the classes. This is the preferred method.

- or -

•	Include a text file as input that gives EXEGEN the necessary directions. Each line of the text file describes one Java class, using the following keywords:

•	class:JavaClassName

Required keyword.

•	clsid:{.....}

Optional keyword that specifies the clsid GUID. If omitted, EXEGEN chooses a unique GUID.

•	progid:ProgId

Optional keyword. If omitted, the class will be registered without a progid.

Working with GUIDs in Java

When an MTS method uses a GUID parameter, you must pass an instance of class com.ms.com._Guid. Do not use class Guid, CLSID or IID from package com.ms.com; they will not work and they are deprecated. The definition of class _Guid is:

package com.ms.com;

public final class _Guid {

// Constructors

public _Guid (String s);

public _Guid (byte[] b);

public _Guid (int a, short b, short c,

byte b0, byte b1, byte b2, byte b3,

byte b4, byte b5, byte b6, byte b7);

public _Guid ();

// methods

public void set(byte[] b);

public void set(String s);

public void set(int a, short b, short c,

byte b0, byte b1, byte b2, byte b3,

byte b4, byte b5, byte b6, byte b7);

public byte[] toByteArray();

public String toString();

}

Instances of this class can be constructed from a String (in the form "{00000000-0000-0000-0000-000000000000}"), from an array of 16 bytes, or from the usual parts of a Guid. Once constructed, the value can also be changed. Method toByteArray will return an array of 16 bytes as stored in the Guid, and method toString will return a string in the same form used by the constructor.

JAVAGUID.EXE

Microsoft Transaction Server supplies a tool, JAVAGUID.EXE, that will post-process the output of JAVATLB. If you are using Visual J++ 6.0 or later, the use of this tool is not required.

JAVAGUID performs the following for each class file:

•	If any method takes a GUID as a parameter, the class of that parameter will be changed to com.ms.com._Guid.

•	If the class file is an interface derived from a type library, a public static final member named iid will be added to the class. This member will contain the interface ID of the interface.

•	If the class file represents a coclass derived from a type library, a public static final member named clsid will be added to the class. This member will contain the CLSID of the class.

JAVAGUID can only be executed from the command line. It takes one or more parameters which are names of class files to update.

The functionality in JAVAGUID has been included with the JACTIVEX tool from Visual J++ 6.0. Additionally, JACTIVEX automatically adds clsid and iid members to COM wrapper classes.

The clsid and iid members are useful as parameters to IObjectContext.CreateInstance and ITransactionContextEx.CreateInstance.

Using an MTS Component from Java

To use an MTS component from Java, run the Java Type Library Wizard against the type library for the component. This will create several Java class files, typically under \%systemroot%\Java\TrustLib. It will create one class file for each custom interface, and one class file for each coclass in the library.

Assume, for example, that the type library contained one interface named IMyInterface, and one coclass, named CMyClass.

From Java, you can create a new instance of the component by executing

new CMyClass()

If you want to control transaction boundaries in the class, you can execute

ITransactionContextEx.CreateInstance ( CMyClass.clsid, IMyInterface.iid )

You should never call Java's new operator on the class that you implemented. Instead, use one of the following techniques:

•	Use Java's new operator on the class created by the Java Type Library Wizard. This will cause the Java VM to call CoCreateInstance.

•	Call MTx.GetObjectContext().CreateInstance (clsid, iid);
This will create a new instance in the same activity as the current instance. This only works if the calling code is itself an MTS component.

•	If you have a reference to an ITransactionContextEx object, call its CreateInstance method. This will create a new instance in the transaction owned by the ITransactionContextEx object.

All of these techinques will result in the creation of a new instance of the class that you implemented.

Using the Java Sample Bank Components

The Java Sample Bank components are automatically configured by MTS Setup and require no additional steps in order to run them.

If you want to recompile the Java Sample Bank components, follow these steps:

1	Run the SetJavaDev.bat file located in the \mts\Samples\Account.VJ folder. Javatlb.exe must be in your path for this batch file to run properly.

2	Recompile your Java component implementation classes.

3	After you recompile the component classes, use the mkdll.bat file located in the \mts\Samples\Account.VJ folder to generate and register vjacct.dll. Exegen.exe must be in your path for this batch file to run properly. You can also add running mkdll.bat as a build step to your Visual J++ project to simplify recompiling.

4	Using the MTS Explorer, import the new components into the Sample Bank package.


Debugging MTS Components

This document describes techniques for debugging MTS components written in Microsoftｮ Visual Basicｮ, Microsoft Visual C++ｮ, and Microsoft Visual J++�. These techniques are just suggestions for successfully debugging MTS components; you can choose your debugging environment and techniques according to your application needs.

If you are using MTS components in a distributed environment, it is recommended that you debug your components on a single computer before deploying to multiple servers. Components that function without error in a package on a local computer usually run successfully over a distributed network. If you do encounter problems with distributed components, you must test and debug both the client and server machines to determine the problem. It is also recommended that you stress test your application with as many clients as possible. You can build a test client that simulates multiple clients to perform the stress test on your application.

To help you debug your components, you should set the MTS transaction timeout to a higher number than the default 60 seconds; otherwise, during debugging, MTS aborts the transaction after this time has lapsed. All subsequent calls to the component return immediately with CONTEXT_E_ABORTED. Any changes to the transaction timeout value made during debugging may not take effect until you restart your debugging environment.

For debugging MTS components written in a specific language, see the following topics:

Debugging Visual Basic MTS Components

Debugging Visual C++ MTS Components

Debugging Java Classes


Debugging Visual Basic MTS Components

Using Visual Basic 6.0

Microsoft Transaction Server components written in Microsoft Visual Basic version 6.0 can be debugged directly in the Visual Basic Integrated Development Environment (IDE).

The following steps describing how to debug a Visual Basic COM component do not apply to Visual Basic version 6.0 or later.

For more information about debugging MTS components using Visual Basic version 6.0, see the Visual Basic version 6.0 documentation.

Using Visual Basic 5.0

Microsoft Transaction Server components written in Microsoft Visual Basic version 5.0 or Visual C++ version 5.0 can be debugged in the Microsoft Visual Studio 97 Integrated Development Environment (IDE).

If you want to debug your components after they are compiled, you cannot use the Visual Basic 5.0 debugger, which only debugs at design time. To debug a compiled Visual Basic component, you will need to use the functionality of the Visual Studio 97 debugger.

Follow these steps to configure Visual Studio to debug MTS components built with Visual Basic 5.0:

1	In Visual Basic, click Properties on the Project menu and then click the Compile tab to select the Compile to Native Code and the Create Symbolic Debug Info checkbox. It is also recommended that you select the No Optimization checkbox while debugging.

2	In the MTS Explorer, right-click the package in which your component is installed, and select the Properties option. Place your cursor over the Package ID, and select and copy the GUID to the clipboard.

3	Open Visual Studio. On the File menu, click Open and select the DLL containing the component that you want to debug.

4	Select Project Settings, and then click the Debug tab. Select the MTS executable for the debug session (winnt\system32\mtx.exe). Enter the program arguments as /p:{<package GUID>} for the package GUID that you copied from the package properties. MTS 2.0 allows for the package name to be used in place of the GUID. Open the .cls files containing the code that you want to debug and then set your breakpoints. If you also want to display variable information in the debug environment, go to the Visual Studio Tools menu, select Options, and then select the Debug tab. In the Debug tab, place a check next to Display Unicode strings.

5	In the MTS Explorer, shut down all server processes.

6	In Visual Studio, select Build, then select Start Debug. Then select Go to run the server process that will host your component(s), and set breakpoints to step through your code.

7	Run your client application to access and debug your components in Visual Studio.

8	Before you deploy your application, remember to select one of the optimizing options in the Compile tab on the Project menu of Visual Basic (set to No Optimization in Step 1), clear the Create Symbolic Debug Info checkbox, and recompile the project.

To facilitate application debugging using Visual Basic 5.0, a component that uses ObjectContext can be debugged by enabling a special version of the object context. This debug-only version is enabled by creating the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Transaction Server\Debug\RunWithoutContext

Note that when running in debug mode, none of the functionality of MTS is enabled. GetObjectContext will return the debug ObjectContext rather than returning Nothing.

When running in this debug mode, the ObjectContext operates as follows:

•	ObjectContext.CreateInstance - calls COM CoCreateInstance (no context flows, no transactions, and so on)

•	ObjectContext.SetComplete - no effect

•	ObjectContext.SetAbort - no effect

•	ObjectContext.EnableCommit - no effect

•	ObjectContext.DisableCommit - no effect

•	ObjectContext.IsInTransaction - returns FALSE

•	ObjectContext.IsSecurityEnabled - returns FALSE

•	ObjectContext.IsCallerInRole - returns TRUE (same as normal when IsSecurityEnabled is FALSE)

You can also develop your own testing message box functions to generate an assert in an MTS Visual Basic component. The following sample code can to used to display error messages while debugging Visual Basic code. You can also use this in conjunction with the Microsoft Windows NTｮ debugger (WinDbg.exe), which is a 32-bit application that, along with a collection of DLLs, is used for debugging the Kernel, device drivers, and applications. Note that you must enter DEBUGGING = -1 in the Conditional Compilation dialog box (located on the Make tab of the Project Properties dialog box) to enable the assert.

The following code provides an example.

#If DEBUGGING Then

    'API Functions

    Private Declare Sub OutputDebugStringA _

        Lib "KERNEL32" (ByVal strError As String)

    Private Declare Function MessageBoxA _

        Lib "USER32" (ByVal hwnd As Long, _

        ByVal lpText As String, _

        ByVal lpCaption As String, _

        ByVal uType As Long) As Long

    'API Constants

    Private Const API_NULL                  As Long = 0

    Private Const MB_ICONERROR              As Long = &H10

    Private Const MB_SERVICE_NOTIFICATION As Long = &H200000

Public Sub DebugPrint(ByVal strError As String)

    Call OutputDebugStringA(strError)

End Sub

Public Sub DebugMessage(ByVal strError As String)

Dim lngReturn As Long

        lngReturn = MessageBoxA(API_NULL, strError, "Error In Component", _

            MB_ICONERROR Or MB_SERVICE_NOTIFICATION)

End Sub

#End If

You can then run checks through your code to aid stress debugging, such as in the following code:

SetobjObjectContext=GetObjectContext()

#If DEBUGGING Then

If objObjectContext Is Nothing Then Call DebugMessage("Context is Not Available")

#End If


Debugging Visual C++ MTS Components

You can use the Visual C++ Integrated Development Environment (IDE)  to debug MTS components written in Visual C++, including components that call SQL Server functions or stored procedures. For more information, see Debugging Visual Basic MTS Components.

The following information applies to components that have their activation property set to In a dedicated server process.

Microsoft Transaction Server supports the COM transparent remote debugging infrastructure. If transparent remote debugging is enabled, then stepping into a client process will automatically stop at the actual object's code in the server process, even if the server is on a different computer on the network. A debugging session is automatically started on the server process if necessary. Similarly, single stepping past the return address of code in a server object will automatically stop just past the corresponding call site in the client's process.

In Microsoft Visual C++, selecting the OLE RPC debugging check box (on the Tools menu, select the Options submenu and choose the Debug property sheet) enables transparent remote debugging. It is not known at this time whether other debuggers support this infrastructure.

You can also debug your Microsoft Transaction Server component DLL in Visual C++ by performing the following steps. Each of these steps is made either inside the MTS Explorer or inside of a Visual C++ session with your MTS DLL project.

1	Shutdown server processes using the MTS Explorer. To do this, right-click My Computer, and select Shutdown Server Process.

2	In your Visual C++ session, under Project, Settings, Debug, General, set the program arguments to the following string: "/p: PackageName", for example:

/p:"Sample Bank"

3	In the same property sheet, set the executable to the full path of the Mtx.exe process, for example: "c:\winnt\system32\MTx.exe".

4	Set breakpoints in your component DLL, and you are ready to debug.

5	Run the server process (in the Build menu, select Start Debug and click Go.)

The following information applies to in-process component DLLs that have their activation property set to In the creator's process.

You can debug your in-process MTS component DLL in Visual C++ by performing the following steps. Each of these steps is made inside a Visual C++ session with your base process project.

1	Set the component DLL under Build, Settings, Debug, Additional DLLs.

2	Now you are ready to step into or set breakpoints in your component DLL at will.

If you are using Visual Studio and Microsoft Foundation Classes (MFC) to debug, the TRACE macro can facilitate your debugging. The TRACE macro is an output debug function that traces debugging output to evaluate argument validity. The TRACE macro expressions specify a variable number of arguments that are used in exactly the same way that a variable number of arguments are used in the run-time function printf. The TRACE macro provides similar functionality to the printf function by sending a formatted string to a dump device such as a file or debug monitor. Like printf for C programs under MS-DOS, the TRACE macro is a convenient way to track the value of variables as your program executes. In the Debug environment, the TRACE macro output goes to afxDump. In the Release environment, the TRACE macro output does nothing.

Example:

// example for TRACE

int i = 1;

char sz[] = "one";

TRACE( "Integer = %d, String = %s\n", i, sz );

// Output: 'Integer = 1, String = one'

The TRACE macro is available only in the debug version of MFC, but a similar function could be written for use without MFC. For more information on using the TRACE macro, see the "MFC Debugging Support" section in Microsoft Visual C++ Programmer's Guide.

Note that you should avoid using standard ASSERT code in Visual C++. Instead, it is recommended that you write assert macros like a MessageBox using the MB_SERVICE_NOTIFICATION flag, and TRACE macro statements using the OutputDebugString function call.


Debugging Java Classes

Using Visual J++ 6.0

Because you can use Visual J++ version 6.0 to debug MTS components completely within the Visual J++ Integrated Development Environment (IDE), the debugging topics below do not apply to Visual J++ 6.0, and are included only for those using earlier versions of Visual J++.

For more information about debugging MTS components in Visual J++ 6.0, please see the Visual J++ 6.0 documentation.

Using Visual J++ 1.1 or 1.0

If you are using Visual J++ 1.1 or earlier, you cannot use the Visual J++ IDE to debug your MTS component. Once your Java class is converted into an MTS component it is not possible to step through the code in the Visual J++ debugger.

Using Visual J++ to Debug Java Classes

Microsoft Visual J++ provides a Java debugger that you can use to set breakpoints in your code. Note that when you are using Visual J++ to debug, if you set a breakpoint in a Java source file before starting the debugging session, Visual J++ may not stop on the breakpoint. For performance reasons, the debugger preloads only the main class of your project. The main class is either the class with the same name as the project or the class you specify in Visual J++. If you use the editor to set breakpoints in other classes before the classes are loaded, the breakpoints are disabled.

You can choose one of the following options to load the correct class so that the debugger stops at breakpoints.

•	Select the class in the category Additional Classes, located on the Debug tab of the Project Settings dialog box, and make sure the first column is checked. This loads the class when the debugging session starts.

•	Right-click a method in the ClassView pane of the Project Workspace and select Set Breakpoint from the Shortcut menu. This causes a break when program execution enters the method.

•	Set the breakpoint after Visual J++ has loaded the class during debugging. You may need to step through your Java source until the class is loaded.

When a method has one or more overloaded versions and shows up as a called method in the Call Stack window, the type and value for the parameters are not displayed in some cases. It appears as though the method takes no parameters. This occurs when the called method is not defined as the first version of the overloaded method in the class definition. For example, see the following class definition:

public class Test

   {

       int method(short s)

       {

           return s;

       }

       int method(int i)

       {

           return i;

       }

   }

If you were looking at a call to the second version of the method in the Call Stack window, it would appear without the type and value for the method:

method()

To view the method's parameters, change the order of the method overloads so that the method that you are currently debugging is first in the class definition.

printf-style Debugging

You can use printf-style debugging to debug your Java classes without using a debugger. printf-style debugging involves including status text messages into your code, allowing you to "step through" your code without a debugger. You can also use printf-style debugging to return error information. The following code shows how you can add a System.out.println call to the try clause of the Hellojtx.HelloObj.SayHello sample.

try

{

System.out.println("This message is from the HelloObj implementation");

result[0] = "Hello from simple MTS Java sample";

MTx.GetObjectContext().SetComplete();

return 0;

}

The client must be a Java client class, and you must use the JVIEW console window to run that class. Note that you need to configure your component to run in the process of its caller, which is in this case JVIEW. Otherwise, this debugging technique results in your component running in the MTS server process (mtx.exe), which would put the println output in the bit bucket rather than the JVIEW console window.

Use the MTS Explorer to configure your component to run in the caller's process by following these steps.

1	Right-click the component.

2	Click the Properties option.

3	Click the Activation tab and clear the In a server process on this computer checkbox.

4	Select the In the creator's process... checkbox.

5	Reload the Client class. Your component's println calls will be visible in the JVIEW console window.

Using the AWT Classes

You can also use the AWT (Abstract Window Toolkit) classes to display intermediate results, even if your component is running in a server process. The java.awt package provides an integrated set of classes to manage user interface components such as windows, dialog boxes, buttons, checkboxes, lists, menus, scrollbars, and text fields.

The following example demonstrates how to use the AWT classes to display intermediate results in a dialog box:

import java.awt.*;

public final class MyMessage extends Frame

{

private Button closeButton;

private Label textLabel;

// constructor

public MyMessage(String msg)

{

super("Debug Window");

Panel panel;

textLabel = new Label (msg, Label.CENTER);

closeButton = new Button ("Close");

setLayout (new BorderLayout (15, 15));

add ("Center", textLabel);

add ("South", closeButton);

pack();

show();

}

public boolean action (Event e, Object arg)

{

if (e.target == closeButton)

{

hide();

dispose();

return true;

}

return false;

}

}

Asynchronous Java Garbage Collection

Note that garbage collection for Java components is asynchronous to program execution and can cause unexpected behavior. This behavior especially affects MTS components that perform functions such as enumerating through the collections in the catalog because the collection count will be too high (garbage collection is not synchronized). To force synchronous release of references to COM or MTS objects, you can use the release method defined in class com.ms.com.ComLib.

Example:

Import com.ms.com.ComLib

�

ComLib.release(someMTSObject);

This method releases the reference to the object when the call is executed. Release the object reference when you are sure that the reference is no longer needed. Note that if you fail to release the reference, an application error is not returned. However, an incorrect collection count results because the object reference is released asynchronously when the garbage collector eventually runs.

You can also force the release of your reference and not call that released reference again.

Example:

myHello = null;

System.gc();

Note that this method of forcing the release of an object reference consumes extensive system resources, and is not guaranteed to work in all cases. For more information, please see Microsoft Knowledge Base article number Q179062 available at http://www.microsoft.com/kb/.

It is recommended that you use the release method defined in com.ms.com.ComLib class to release references to MTS objects in a synchronous fashion.


Automating MTS Deployment

This document describes how you can use the scriptable administration objects to automate deployment and distribution of your MTS packages. The MTS Explorer lets you configure and deploy packages by using a graphical user interface rather than by programming code. However, you can use the scriptable administrative objects to automate administration tasks, such as program configuration and deployment. Note that the scriptable administrative objects support the same collection hierarchy as the MTS Explorer. The following figure shows the MTS Explorer collection hierarchy.

For more information about MTS Explorer functionality, see the Administrator's Guide.

Using the Scriptable Administration Objects

Microsoft Transaction Server contains Automation objects that you can use to program administrative and deployment procedures, including:

•	Installing a Pre-Built Package

•	Creating a New Package and Installing Components

•	Enumerating Through Installed Packages to Update Properties

•	Enumerating Through Installed Packages to Delete a Package

•	Enumerating Through Installed Components to Delete a Component

•	Accessing Related Collection Names

•	Accessing Property Information

•	Configuring a Role

•	Exporting a Package

•	Configuring a Client to Use Remote Components

Note that you can use the scriptable administration objects to automate any task in the MTS Explorer.

The scriptable administration objects are derived from the IDispatch interface, so you can use any Automation language to develop your package, such as Microsoftｮ Visual Basicｮ version 5.0, Microsoft Visual C++ｮ version 5.0, Microsoft Visual Basicｮ Scripting Edition (VBScript), and Microsoft JScript�.

Each folder in the MTS Explorer hierarchy corresponds to a collection stored in the catalog data store. The following scriptable objects are used for administration:

•	Catalog

•	CatalogObject

•	CatalogCollection

•	PackageUtil

•	ComponentUtil

•	RemoteComponentUtil

The Catalog, CatalogObject, and CatalogCollection scriptable objects provide top-level functionality such as creating and modifying objects. The Catalog object enables you to connect to specific servers and access collections. Call the CatalogCollection object to enumerate, create, delete, and modify objects, as well as to access related collections. CatalogObject allows you to retrieve and set properties on an object. The Package, Component, Remote Component, and Role objects enable more specific task automation, such as installing components and exporting packages. This utility layer allows you to program very specific tasks for collection types, such as associating a role with a user or class of users.

The following diagram illustrates how the MTS scriptable administration objects interact with the MTS Explorer catalog:

Interface	Description
ICatalog	The Catalog object enables you to connect to specific servers and access collections.
ICatalogCollection	The CatalogCollection object can be used to enumerate objects, create, delete, and modify objects, and access related collections.
ICatalogObject	The CatalogObject object provides methods to get and set properties on an object.
IPackageUtil	The IPackageUtil object enables a package to be installed and exported within the Packages collection.
IComponentUtil	The IComponentUtil object provides methods to install a component in a specific collection and to import components registered as an in-process server.
IRemoteComponentUtil	You can use the IRemoteComponentUtil object to program your application to pull remote components from a package on a remote server.
IRoleAssociationUtil	Call methods on the IRoleAssociationUtil object to associate roles with a component or component interface.
For example, you can automate creating a new package and installing components into the new package by using the scriptable objects in the utility layer (Package, Component, Remote Component, and Role objects).

The following Visual Basic sample shows how to use the scriptable administration objects to create and install components into a new package named "My Package."

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

Dim catalog As Object

Dim packages As Object

Dim newPack As Object

Dim componentsInNewPack As Object

Dim util As Object

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

On Error GoTo failed

3	Call the CreateObject method to create an instance of the Catalog object. Retrieve the top level Packages collection from the CatalogCollection object by calling the GetCollection method. Then call the Add method to add a new package.

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

Set newPack = packages.Add

Dim newPackID As String

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

newPackID = newPack.Key

newPack.Value("Name") = "My Package"

packages.savechanges

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

Set componentsInNewPack =
    packages.GetCollection("ComponentsInPackage",
    newPackID)

Set util = componentsInNewPack.GetUtilInterface

util.InstallComponent"d:\dllfilepath", "", ""

Exit Sub

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

failed:

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

End Sub

For a complete description of how to program these procedures and more sample code, refer to the Administrator's Guide.


MTS Error Diagnosis

This topic describes how to determine the source of an error in your MTS application. You can diagnose the source and obtain a description of application errors by using a combination of Microsoftｮ Windows NTｮ, MTS, and other tools. If you discover that the application error is caused by MTS, you can interpret the error message using the Win32 (Win32.h) or MTS header files (mts.h), or the Microsoft Visual C++ｮ error utility.

For more information on debugging an MTS application, see Debugging MTS Components.

Finding the Source of the Error

If your server application is failing or causing unexpected behavior, you must first determine where your error occurred. Windows NT provides a system Event Viewer that tracks application, security, and system events. Refer to the Application Log in the Event Viewer first to check the application associated with the event message. (Because you can also archive event logs, you can track an event history of the error.) Selecting an entry in your log activates an Event Detail, which provides further information about the system event. If you attempt to run the Sample Bank client without starting the Microsoft Distributed Transaction Coordinator (MS DTC), you will be returned the following Automation error.

Since this error does not indicate which application caused the failure, you can reference the Application Log in the Event viewer, which shows the error was caused by MTS.

Note   If you are using MTS for Windows 98, events are written to text files in the \Windows\MTSLogs directory.

Interpreting Error Messages

The Event Viewer helps you determine the application source of the problem. You can use other tools to interpret individual error messages. Success, warning, and error values are returned using a 32-bit number known as a result handle, or HRESULT. HRESULTs are 32-bit values with several fields encoded in the value. A zero result indicates failure if that bit is set. A non-zero result can be a warning or informational message.

HRESULTs work differently, depending on the platform you are using. On 16-bit platforms, an HRESULT is generated from a 32-bit value known as a status code, or SCODE. On 32-bit platforms, an HRESULT is the same as an SCODE. Note that if you are returning HRESULTs from Java, you should throw an instance of com.ms.com.ComFailException to indicate failure. You can specify a particular HRESULT when constructing the ComFailException object. The HRESULT is used as the return value for the COM method. To indicate successful completion, you do not need to do anything; just return normally. To return S_FALSE, indicating a successful completion but a return value of Boolean False, throw an instance of com.ms.com.ComSuccessException. In Visual Basic, you use the Err.Raise function to set and the On Error� / Err.Number to retrieve HRESULTs.

For a list of the values of common system-defined HRESULTs, see ComFailException. For a complete list of system-defined HRESULT values, see the header file Winerror.h included with the Platform SDK.

MTS never changes the value of an HRESULT error code, such as E_UNEXPECTED or E_FAIL, returned by an MTS object method. When an MTS object returns an HRESULT status code (such as S_OK or S_FALSE), MTS may convert the status code into an MTS error code before it returns to the caller. This occurs, for example, when the application returns S_OK after calling the SetComplete function; if the object is the root of an automatic transaction that fails to commit, the HRESULT is converted to CONTEXT_E_ABORTED. When MTS converts a status code to an error code, all the method's output parameters are cleared. Returned references are released and the values of the returned object pointers are set to NULL.

The Mtx.h header file contains the MTS specific error codes. Winerror.h contains the error code definitions for the Win32 API. For an overview of error codes, see "Error Handling" in the COM portion of the Microsoft Platform SDK

You can also use the ERRLOOK utility in Microsoft Visual Studio� 97 to retrieve a system error message or module error message based on the value entered. ERRLOOK retrieves the error message text automatically if you drag-and-drop a hexadecimal or decimal value from the Visual Studio debugger or other Automation-enabled application. You can also enter a value either by typing it in or pasting it from the IDE clipboard and clicking the Look Up option.

Contacting MTS Support

If you run into a problem that you cannot solve, you can contact Microsoft support with the following information:

•	Topography of the application where the error occurred, such as a description of packages, components, and interfaces

•	Application event log on all computers

•	Reproduction of the error, if possible

Troubleshooting

If you are having trouble diagnosing your problem, refer to the list of troubleshooting tips below:

•	Make sure that the Distributed Transaction Coordinator (DTC) is running on all servers.

•	Check network communication by first testing on a local computer to verify that the application works. If you are running TCP/IP on your network, you can then use the Windows NT Ping.exe utility to verify that the machines are on the network.

•	Make sure that SQL and DTC are either located on the same computer or that the DTC Client Configuration program specifies that the DTC is on another computer. If not, SQLConnect will return an error internally when called from a transactional component.

•	Set the MTS transaction timeout to a higher number than the default 60 seconds; otherwise, during debugging, MTS aborts the transaction after this time has lapsed. All subsequent calls to the component return immediately with CONTEXT_E_ABORTED.

Note   Any changes to the transaction timeout value made during debugging may not take effect until you restart your debugging environment.

•	Make sure that your ODBC drivers are thread-safe and do not have thread affinity.

•	If you have difficulty getting an application to work over several servers, reboot the client and then verify that your Windows NT domain controller is configured properly.

•	Turning off resource pooling may reveal that a resource dispenser used by your application is the source of the problem. You can turn off resource pooling by setting the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Transaction Server\Local Computer\My Computer:Resource Pooling=N

See the DCOM documentation and DCOM-related Knowledge Base articles if you are experiencing application errors that you suspect are caused by DCOM.


Creating a Simple ActiveX Component (Visual Basic)
Creating a Simple ActiveX Component

This section gets you started quickly with a simple ActiveX� component (Account). You then install, run, and monitor Account with the Microsoft Transaction Server (MTS) Explorer and a sample client (Bank).

	Scenario: Creating and Using a Simple ActiveX Component First, create your component (Account) and run it in the MTS run-time environment by using the Bank client. Then, add a database connection to Account and run it again.
	Creating the Account Component Create a new ActiveX component, Account.
	Creating the Bank Package Use the MTS Explorer to create a new package for your component.
	Installing the Account Component in the Bank Package Use the MTS Explorer to install your component in a package.
	Running and Monitoring the Account Component Use the Bank client to run your component, and use the MTS Explorer to monitor it.
	Modifying the Account Component: Add a Database Connection Modify your component so that it connects to a database. The connection will be pooled by the ODBC resource dispenser. Then use the Bank client to re-run the modified component.
	Application Design Notes: Sharing Resources Learn how to efficiently share resources, such as database connections, through the MTS Resource Dispenser Manager and resource dispensers.
See Also

Programming Concepts, Transaction Server Components, Building Scalable Components


Scenario: Creating and Using a Simple ActiveX Component (Visual Basic)
Scenario: Creating and Using a Simple ActiveX Component

This scenario has two implementation stages. The initial stage consists of building a simple component: the Account component. You can implement Account by creating a project (Account.vbp) with a class module (Account.cls). The Account class module exposes one method, Post, that passes back a string indicating that it was called successfully. The following illustration depicts the first stage of this scenario.

The second stage of this scenario adds a database connection to get the appropriate account information from a database and update it. This demonstrates using a resource dispenser — in this case, the ODBC resource dispenser, which enables efficient connection pooling. The following illustration depicts the second stage of this scenario.

The rest of this section provides step-by-step instructions for creating, installing, and running the Account component in this scenario. You can find the Microsoft Visual Basic projects for each of these steps in the Step1 through Step8 folders in the \Samples\Account.VB folder of your Microsoft Transaction Server installation.

See Also

Programming Concepts, Application Design Notes: Sharing Resources, Transaction Server Components, Building Scalable Components, Creating the Account Component, Run and Monitor the Account Component, Modifying the Account Component, Application Design Notes: Resource Usage, Creating a Simple ActiveX Component


Creating the Account Component (Visual Basic)
Creating the Account Component

The first step toward building a simple application that you can use with Microsoft Transaction Server (MTS) is to create a simple ActiveX� component DLL (VBAcct.dll); the Account component provides one method, Post.

The information presented here assumes a basic understanding of how to use Microsoft Visual Basic to create ActiveX components.

Note   You cannot install executable files (.exe) in MTS. If you have a component built as an executable file, you must rebuild it as a dynamic-link library (DLL).

To create the Account component

1	Start Microsoftｮ Visual Basic� and open the \Mts\Samples\Account.VB\Step1\Account.vbp project.

Click here to see the code for the Account component

2	Build the component as a DLL and save it as \Mts\Samples\Account.VB\Step1\VBAcct.dll.

See Also

Programming Concepts, Transaction Server Components, Building Scalable Components, Transaction Server Component Requirements, Run and Monitor the Account Component, Application Design Notes: Sharing Resources, Modifying the Account Component, Application Design Notes: Resource Usage, Creating a Simple ActiveX Component


Creating the Bank Package (Visual Basic)
Creating the Bank Package

To run your component in the MTS run-time environment, you need to create a package. For this scenario, you will create a package with a single component.

A package is a collection of components that you can deploy and manage as a unit. By grouping components into packages, you define the security and process boundaries for components running on a computer. The criteria for deciding how to group components into packages require achieving the optimum balance between performance, fault isolation, and load balancing.

You will create a package called Bank that will contain the Account component.

To create the Bank package

1	On the Start menu, point to Programs, point to Microsoft Transaction Server, and then click Transaction Server Explorer.

2	Create a new package named Bank. In the Set Package Identity dialog box, select Interactive user.

How?

You can use the General, Security, Advanced, Identity, and Activation tabs to configure a package. For this scenario, you will use the default settings for the package you just created.

See Also

What Does Creating a Package Mean?, Package Properties , Programming Concepts, Installing the Account Component in the Bank Package, Creating a Simple ActiveX Component


Installing the Account Component (Visual Basic)
Installing the Account Component

To run your components in the Microsoft Transaction Server run-time environment, you first need to install them in a package. This means you need to install the Account component in the Bank package.

To install the Account component

•	Install the Account component into the Bank package you created in Creating the Bank Package. Use the Account component that you built in \Mts\Samples\Step1\Account.VB\VBAcct.dll.

How?

You can use the General, Transaction, and Security tabs to configure a component. For this scenario, you will use the default settings for the component you just installed.

See Also

Adding A Component to a Package, Component Properties , Creating the Bank Package, Creating a Simple ActiveX Component


Running and Monitoring the Account Component (Visual Basic)
Running and Monitoring the Account Component

Now that you have created the Bank package and installed the Account component in the Microsoft Transaction Server Explorer, you can run the Account component with the Bank client and monitor the component status in the Explorer.

Running your component in MTS brings immediate benefits to your application, even if it doesn't implement any of the MTS APIs. Such benefits include:

•	Simplified management of your components though an easy-to-use graphical tool, the MTS Explorer.

•	Location transparency--the ability to run your components in-process, locally, or remotely.

•	Thread management and component tracking.

•	Database connection pooling through the Resource Dispenser Manager and the ODBC resource dispenser (automatically provided if you call the ODBC API).

To run and monitor your component

1	In the left pane of the MTS Explorer, click the Components folder where you installed the Bank.Account component.

2	On the View menu, click Status view to display usage information for the Bank.Account component.

3	On the Start menu, point to Programs, point to Microsoft Transaction Server, and then click Bank Client.

Arrange the windows so that you can see the Bank Client window and the MTS Explorer window simultaneously. The form will default to credit $1 to account number 1.

4	In the Bank client, click the Account component.

5	Click Submit.

You should see the response Hello from Account.

6	In the Bank client, change the iterations from 1 of 0 to 1 of 100 and click Submit.

In the right pane of the MTS Explorer, you should see the values under the Objects and Activated columns change to 1 and back to 0.

See Also

Status View, Creating the Bank Package, Installing the Account Component in the Bank Package, Microsoft Transaction Server APIs, Maintaining MTS Packages, Creating a Simple ActiveX Component


Modifying the Account Component to Use the ODBC Resource Dispenser (Visual Basic)
Modifying the Account Component to Use the ODBC Resource Dispenser

In this section, you enhance the Account component by adding a database connection. You revise the Post method to access a database using ActiveX Data Objects (ADO) to obtain the appropriate account information. This demonstrates using a resource dispenser — in this case, the ODBC resource dispenser, which enables connections to be pooled for efficiency. You will also add a new class module, CreateTable, to the Account project.

To modify the Account component

1	Open the \Mts\Samples\Account.VB\Step2\Account.vbp project.

Click here to see the modified Account component

2	Build the component as a DLL and save it as \Mts\Samples\Account.VB\Step2\VBAcct.dll.

By adding a new class module, you have added a new COM component to this DLL. Therefore, you will need to delete the Account component in the Microsoft Transaction Server Explorer and then install the Account and the MoveMoney components.

To reinstall your components

1	Remove the Account component.

How?

2	Add the new components.

How?

Use the DLL you created in \Mts\Samples\Account.VB\Step2\VBAcct.dll.

You can now run the new component by using the Bank client. You should see a response Credit, balance is $ 1. (VB).

See Also

Creating the Account Component, Application Design Notes: Resource Usage, Programming Concepts, Creating a Simple ActiveX Component


Application Design Notes: Sharing Resources (Visual Basic)
Application Design Notes: Sharing Resources

Each time the Account object's Post method is called, it obtains, uses, and then releases its database connection. A database connection is a valuable resource. The most efficient model for resource usage in scalable applications is to use them sparingly, acquire them only when you really need them, and return them as soon as possible.

Historically, acquiring resources has been an expensive operation in terms of system performance. Many programs have adopted a strategy of acquiring resources and holding onto them until program termination. While this strategy is effective for single-user systems, building scalable server applications requires sharing these resources.

Microsoft Transaction Server provides an architecture for resource sharing through its Resource Dispenser Manager and resource dispensers. The Resource Dispenser Manager works with specific resource dispensers to automatically pool and recycle resources. The ODBC version 3.0 Driver Manager is a Microsoft Transaction Server resource dispenser, also referred to as the ODBC resource dispenser.

Although the Account component hasn't implemented any of the MTS-specific APIs, when you run it, MTS uses the ODBC resource dispenser. This happens automatically when the Post method uses ActiveX Data Objects (ADO) to access the database, because ADO in turn uses ODBC. Whenever any component running in the MTS run-time environment uses ODBC directly or indirectly, the component automatically uses the ODBC resource dispenser.

When the Account object releases the database connection, the connection is returned to a pool. When the Post method is called again, it requests the same database connection. Instead of creating a new connection, the ODBC resource dispenser recycles the pooled connection, which saves time and server resources.

The topic Building Scalable Components, shows you how to use just-in-time activation to use server resources even more efficiently, resulting in more scalable applications and improved performance.

See Also

Application Design Notes: Resource Usage, Building Scalable Components, Modifying the Account Component, Creating the Account Component, Creating a Simple ActiveX Component


Building Scalable Components (Visual Basic)
Building Scalable Components

In this section, you'll learn how you can use just-in-time activation to use server resources efficiently, resulting in more scalable applications and improved performance. You'll also see how a simple change to the Account component allows it to scale efficiently and support a large number of clients, without requiring you to make any changes to the client.

	Scenario: Adding Just-In-Time Activation to the Account Component Add code to your Account component to take advantage of just-in-time activation, which releases the component's resources when Account has completed its work.
	Adding Code to Call GetObjectContext, SetComplete, and SetAbort Add code to call GetObjectContext, SetComplete, and SetAbort.
	Application Design Notes: Just-In-Time Activation Learn how to reuse resources efficiently so you can build scalable applications.
See Also

Context Objects, Deactivating Objects, Creating a Simple ActiveX Component, GetObjectContext method, SetAbort method, SetComplete method


Scenario: Adding Just-In-Time Activation to the Account Component (Visual Basic)
Scenario: Adding Just-In-Time Activation to the Account Component

In this scenario, the Bank client creates an Account object from the Account component and calls its Post method, just as in Creating a Simple ActiveX Component. This time, Account obtains a reference to its context object. When it successfully completes its work on behalf of the client, it uses its context object to call SetComplete. If Account encounters an error and is unable to complete its work successfully, it uses its context object to call SetAbort. When Account calls either SetComplete or SetAbort, it indicates that it's finished with its work and that it doesn't need to maintain any private state for its client. This allows the MTS run-time environment to reclaim and reuse the Account object's resources.

See Also

Context Objects, Deactivating Objects, Application Design Notes: Just-In-Time Activation, GetObjectContext method, SetAbort method


Adding Code to Call GetObjectContext, SetComplete, and SetAbort (Visual Basic)
Adding Code to Call GetObjectContext, SetComplete, and SetAbort

Every Transaction Server object has a context object associated with it. The context object is automatically created at the same time the object itself is created. You can use an object's context to declare when the object's work is complete, as shown in the following illustration.

Calling either of these methods notifies the MTS run-time environment that it can safely deactivate the object, making its resources available for reuse.

To implement the scenario for this chapter, you will modify the Post method to use the Account object's context object. Then you will use SetComplete and SetAbort to enable just-in-time activation.

First, you call GetObjectContext to get a reference to the context object. When an object has completed its work successfully, it should call SetComplete:

GetObjectContext.SetComplete

SetComplete notifies the MTS run-time environment that the Account object should be deactivated as soon as it returns control to the Bank client.

If the object encountered an error, it should call SetAbort. SetAbort also notifies the MTS run-time environment that the Account object should be deactivated as soon as it returns control to the Bank client.

GetObjectContext.SetAbort

To obtain a reference to an object's context

1	Open the \Mts\Samples\Account.VB\Step3\Account.vbp project.

Click here to see the Post method

2	Build the component as a DLL and save it as \Mts\Samples\Account.VB\Step3\VBAcct.dll.

Before you can run your new component again in MTS, the registry needs to be updated with the new component information. To do this, refresh the MTS Explorer window.

If you install the Development version of Microsoft Transaction Server, you will get a Visual Basic - compatible add-in that automates this process for you (select the VB Addin box during Setup). The next time you run Visual Basic, the add-in is automatically installed in Visual Basic. The add-in automatically refreshes all of your MTS component DLLs whenever you recompile your project.

You can also turn this feature on and off on a per-project basis by using the toggle command on the Visual Basic Add-Ins menu. To turn it on, on the Visual Basic Add-Ins menu, point to MS Transaction Server, and click AutoRefresh after compile of active project. This puts a check mark next to the command, indicating that the feature is activated. If you want to refresh all of your MTS components at any given time, on the Visual Basic Add-Ins menu, point to MS Transaction Server, and then click Refresh all components now.

Now you'll run the Account component again from the Bank client, and monitor its execution in the MTS Explorer's Status window. Follow the same steps as in "Running and Monitoring the Account Component."

When the Bank client creates the Account object, the number 1 will appear under Objects and Activated. This indicates that one object is executing in the MTS run-time environment, and that it is currently activated. When the client calls the Post method, the number 1 appears, briefly, under In Call. This indicates that one object is currently executing a method call. When the Post method returns control to the client, the number under Objects is still 1, but the numbers under Activated and In Call return to 0. This is because after calling SetComplete, the object is deactivated as soon as it returns from the current method call.

Note   Because the Post method executes so quickly, you may not actually see this sequence appear.

See Also

Context Objects, Deactivating Objects, Creating a Simple ActiveX Component, GetObjectContext method, SetAbort method, SetComplete method


Application Design Notes: Just-In-Time Activation (Visual Basic)
Application Design Notes: Just-In-Time Activation

When you design a traditional application, you have two options:

•	A client can create, use, and release an object. The next time it needs the object, it creates it again.

The advantage to this technique is that it conserves server resources. The disadvantage is that, as your application scales up, your performance slows down. If the object is on a remote computer, each time an object is created, there must be a network round-trip, which negatively affects performance.

•	A client can create an object and hold onto it until the client no longer needs it.

The advantage of this approach is that it's faster. The problem with it is that, in a large-scale application, it quickly becomes expensive in terms of server resources.

While either of these approaches might be fine for a small-scale application, as your application scales up, they're both inefficient. Just-in-time activation provides the best of both approaches, while avoiding the disadvantages of each.

In Creating a Simple ActiveX Component, the Bank client controlled the Account object's life cycle. Clients held onto server resources even when the clients were idle. As you added more clients, you saw a proportional increase in the number of allocated objects and database connections. A quick look at the Account component shows that each call to the Post method is independent of any previous calls. An Account object doesn't need to maintain any private state to correctly process new requests from its client. It also doesn't need to maintain its database connection between calls. The only problem is that, in this scenario, the MTS run-time environment can't reclaim the object's resources until the client explicitly releases the object. If you have to depend on your clients to manage your object's resources, you can't build a scalable component.

By adding just a few lines of code, you were able to implement just-in-time activation in the Account component. When an Account object calls SetComplete, it notifies the MTS run-time environment that it should be deactivated as soon as it returns control to the client. This allows the MTS run-time environment to release the object's resources, including any database connection it holds prior to the object's release. The Bank client continues to hold a reference to the deactivated Account object.

When a client calls a method on a deactivated object, the client's reference is automatically bound to a new object. Thus, the client has the illusion of a continuous reference to a single object, without tying up server resources unnecessarily.

Although the call to SetAbort has a similar effect, it isn't apparent in this scenario why it is used when errors occur. The next chapter, Building Transactional Components, shows you how transactions can make your applications more robust in the event of an error.

See Also

Context Objects, Deactivating Objects, Creating a Simple ActiveX Component, GetObjectContext method, SetAbort method, SetComplete method


Building Transactional Components (Visual Basic)
Building Transactional Components

This section introduces transactional components and the benefits of running components within the same transaction.

	Scenario: Composing Work from Multiple Components Under the Same Transaction Add new functionality to transfer money between accounts by adding a new component, MoveMoney, which uses the existing Account component.
	Creating the MoveMoney Component Use the CreateInstance method to run the MoveMoney and Account components within the same transaction.
	Monitoring Transactions Use the Bank client to run your components, and use the Microsoft Transaction Server Explorer to monitor transactions.
	Application Design Notes: Using Context and Transactions Using transactional components provides atomicity and simplified error recovery.
See Also

Transactions, Transaction Attributes, ObjectContext object, CreateInstance method


Scenario: Composing Work from Multiple Components Under the Same Transaction (Visual Basic)
Scenario: Composing Work from Multiple Components Under the Same Transaction

For this scenario, you will add new functionality that allows you to transfer money between two accounts. To implement this, you add a new component, MoveMoney. MoveMoney creates Account and then calls it once for a credit or debit, or twice for a transfer, as shown here.

Because either MoveMoney or Account could fail at any point, all database updates need to be in the same transaction to ensure that the database remains consistent. To do this, you configure the MoveMoney and Account components in the Microsoft Transaction Server Explorer to require a transaction. Transaction Server ensures that all their objects' work is automatically done in the same transaction.

See Also

Transactions, Transaction Attributes


Creating the MoveMoney Component (Visual Basic)
Creating the MoveMoney Component

To implement this scenario, you will add a new class module, MoveMoney, to the Account project. MoveMoney has a single method, Perform, which creates an Account object to perform the credit, debit, or transfer.

To create the MoveMoney component

1	Open the \Mts\Samples\Account.VB\Step4\Account.vbp project.

Click here to see the Perform method

2	Build the component as a dynamic-link library (DLL) and save it as \Mts\Samples\Account.VB\Step4\VBAcct.dll.

By adding a new class module, you have added a new COM component to this DLL. Therefore, you will need to delete the Account component in the Microsoft Transaction Server Explorer and then install the Account and the MoveMoney components.

To reinstall your components

1	Remove the Account and CreateTable components.

How?

2	Add the new components.

How?

Use the DLL you created in the previous procedure. You can find it in \Mts\Samples\Account.VB\Step4\VBAcct.dll.

MTS enlists a component in a transaction as specified by the component's transaction attribute. For this scenario, Account and MoveMoney run within the same transaction.

To set the transaction attributes for your components

1	For the Account and MoveMoney components, set the transaction attribute to Requires a transaction.

2	For the CreateTable component, set the transaction attribute to Requires a new transaction.

How?

The MoveMoney object uses CreateInstance to create the Account object. CreateInstance is a method on the context object. By using CreateInstance, the Account object created by MoveMoney shares context with MoveMoney.

Dim objAccount As Bank.Account

Set objAccount = _

    GetObjectContext.CreateInstance("Bank.Account")

Transactions are associated with an object's context. Because both MoveMoney and Account have a transaction attribute of Requires a transaction, the Account object will be enlisted within the same transaction as MoveMoney.

In Building Scalable Components, you learned how to use SetComplete to indicate that an object has finished its work and can be deactivated. For transactional components, calling SetComplete indicates that a transaction can be committed.

GetObjectContext.SetComplete

When the Perform method returns, the transaction attempts to commit. There is no guarantee that it will commit, however. If an error occurs, Perform instead calls SetAbort.

GetObjectContext.SetAbort

SetAbort also indicates that an object has finished its work, but that it isn't in a consistent state. When the Perform method returns after calling SetAbort, the attempt to commit the transaction won't succeed.

See Also

Transactions, Transaction Attributes, Context Objects, Creating MTS Objects, ObjectContext object, CreateInstance method, GetObjectContext method, SetAbort method, SetComplete method


Monitoring Transaction Statistics (Visual Basic)
Monitoring Transaction Statistics

You can use the Microsoft Transaction Server Explorer to monitor commit and abort statistics for transactions.

You can experiment with the MoveMoney and Account components to see how transactions are committed and aborted as you provide user input with the Bank client.

To monitor transactions

1	On the Window menu of the Transaction Server Explorer, click New Window.

2	In the left pane, click Transaction Statistics.

3	On the Action menu, click Scope Pane to hide the left pane of the Explorer.

4	Make sure that the Microsoft Distributed Transaction Coordinator (MS DTC) is running on your SQL Server computer. You can start MS DTC from the Transaction Server Explorer or from SQL Server.

5	Also make sure that you have the ODBC data source set up, and that SQL Server is running. Click [image] to get information on how to do this.

6	Start the Bank client.

Rearrange the windows so that you see the two Microsoft Transaction Server Explorer windows and the Bank client window.

To monitor a commit, click Submit in the Bank client. The Transaction Statistics window first indicates that one transaction is active, and indicates that one transaction was committed.

To monitor an abort, click Debit in the Bank client, and enter an amount for the transaction that is greater than the balance on your account. Click Submit. The Transaction Statistics window first indicates that one transaction is active, and then indicates that one transaction was aborted.

Try experimenting with Transfer. Verify that both objects are running within the same transaction by checking the balance of two accounts and performing a transfer that would overdraw from an account. Notice that both the credit and the debit are aborted.

See Also

Monitoring Transactions in MTS


Application Design Notes: Using Context and Transactions (Visual Basic)
Application Design Notes: Using Context and Transactions

Context simplifies defining transactions. A transaction is automatically started when a component is declared as transactional. Components don't need to add additional code to indicate the start and end of a transaction. Using context allows you to define the scope of a transaction.

Besides simplifying building components, automatic transaction enlistment also allows for reuse of existing components. Changing the transaction attribute is the only change to the Account component from the previous section, Building Scalable Components.

Creating the Account object from MoveMoney establishes MoveMoney as the root of the transaction. The root transaction attempts to commit after it has completed its work. If an Account object calls SetAbort to indicate that it cannot successfully commit its work, then when the root transaction attempts to commit, the entire transaction will fail.

In the case of a money transfer, this provides atomicity. If a credit succeeds, but insufficient funds prevent the debit from succeeding, then the credit will be rolled back from the database automatically. Thus, SetAbort provides simplified error recovery.

Context simplifies the development of the component. Each object independently acquires its own resources, performs its work, and indicates its own internal state by using SetComplete or SetAbort before returning.

See Also

Transactions, Transaction Attributes, Context Objects, CreateInstance method, ObjectContext object, SetAbort method, SetComplete method


Sharing State (Visual Basic)
Sharing State

This chapter shows you how to use the Shared Property Manager to share state among multiple Microsoft Transaction Server objects running in the same process.

	Scenario: A Receipt Number Generator That Uses the Shared Property Manager Create a component that uses the Shared Property Manager to generate a unique receipt number for each bank transaction.
	Creating the Receipt Component Create a SharedProperty object to get a new receipt number, with appropriate isolation and release modes for this scenario.
	Application Design Notes: Sharing State by Using the Shared Property Manager Learn some of the advantages of using the Shared Property Manager to manage shared state within a process.
See Also

Resource Dispensers, Stateful Components, SharedPropertyGroupManager object


Scenario: A Receipt Number Generator That Uses the Shared Property Manager (Visual Basic)
Scenario: A Receipt Number Generator That Uses the Shared Property Manager

This chapter introduces the Receipt component, which dispenses unique receipt numbers for fund transfers. When a bank transaction takes place, the MoveMoney object creates a Receipt object. The Receipt component contains a single method, GetNextReceipt.

GetNextReceipt uses the Shared Property Manager to get a unique receipt number. The Shared Property Manager has an object hierarchy as shown in the following figure:

Within a server process, there is only one instance of the SharedPropertyGroupManager object. The value of the receipt number is maintained by a SharedProperty object, which provides locking mechanisms to ensure that no two calls to GetNextReceipt retrieve the same value.

See Also

Resource Dispensers, Creating the Receipt Component, Application Design Notes: Sharing State by Using the Shared Property Manager, SharedPropertyGroupManager object, SharedPropertyGroup object, SharedProperty object


Creating the Receipt Component (Visual Basic)
Creating the Receipt Component

The Receipt component contains a single method, GetNextReceipt. The Receipt object itself doesn't maintain the value of the receipt number between calls. The Shared Property Manager maintains these values. The Receipt object calls a SharedProperty object to get a new receipt number.

You will also add code to the MoveMoney component to call the Receipt component.

To create the Receipt Component

1	Start Microsoft Visual Basic and open the \Mts\Samples\Account.VB\Step5\Account.vbp project.

Click here to see the code for the Receipt component

Click here to see the code for the MoveMoney component

2	Build the component as a DLL and save it as \Mts\Samples\Account.VB\Step5\VBAcct.dll.

By adding a new class module, you add a new COM component to this DLL. Therefore, you need to delete the existing components in the Microsoft Transaction Server Explorer and then install the new components.

To reinstall your components

1	Remove the Account, MoveMoney, and CreateTable components from the Transaction Server Explorer.

How?

2	Add the new components. Use the DLL you created in \Mts\Samples\Account.VB\Step5\VBAcct.dll.

How?

To set the transaction attributes for your components

1	For the Account and MoveMoney components, set the transaction attribute to Requires a transaction.

How?

2	For the CreateTable component, set the transaction attribute to Requires a new transaction.

3	For the Receipt component, set the transaction attribute to Does not support transactions. This is the default value.

Note that the Receipt component is not transactional because the receipts are maintained as properties in memory and aren't durable.

When you run the Bank Client, select the MoveMoney button under Component. You should see the response Credit, balance is $ 1. (VB); Receipt No: #####.

The various object creation methods for Shared Property Manager objects are designed for simplified coding. If the object doesn't exist, it will be created. If it already exists, the object is returned. GetNextReceipt makes the following method call to access the shared property group manager:

Set spmMgr = CreateObject _

    ("MTxSpm.SharedPropertyGroupManager.1")

This code works every time it is called. There is no need to check if the shared property group manager has already been created. Such behavior also ensures that only one instance of the SharedPropertyGroupManager object exists per server process.

For the SharedPropertyGroup and SharedProperty objects, a flag is returned to indicate whether the property group or property already exists. The following code shows how this flag is used to determine if the property needs to be initialized:

Set spmPropNextReceipt = _

    spmGroup.CreateProperty("Next", bResult)

' Set the initial value of the SharedProperty to

' 0 if the SharedProperty didn't already exist.

If bResult = False Then

    spmPropNextReceipt.Value = 0

End If

Access to shared properties is controlled through the CreatePropertyGroup method:

Set spmGroup = _

    spmMgr.CreatePropertyGroup("Receipt", _

    LockMethod, Process, bResult)

CreatePropertyGroup has two parameters, isolation mode and release mode. The isolation mode for the Receipt property group is set to LockMethod, which ensures that two instances of the Receipt object can't read or write to the same property during a call to GetNextReceipt. The release mode for the Receipt property group is set to Process, which maintains the property group until the server process is terminated.

See Also

Application Design Notes: Sharing State by Using the Shared Property Manager, SharedPropertyGroupManager object, CreateProperty methodasmthCreatePropertyvb, CreatePropertyGroup methodasmthCreatePropertyGroupvb


Application Design Notes: Sharing State by Using the Shared Property Manager (Visual Basic)
Application Design Notes: Sharing State by Using the Shared Property Manager

Using the Shared Property Manager makes sharing state in a multiuser environment as easy as it is in a single-user environment. Without the use of the Shared Property Manager, the application would require much more code that has nothing to do with the business problem at hand.

One alternate way to create the same functionality would be to maintain the receipt number as a member variable of the Receipt component. However, this complicates coding the Receipt component immensely. The Receipt component would have to remain persistent in memory during the life of the server process. This would require the following additional code:

•	Referencing all instances of MoveMoney to the Receipt object.

•	Maintaining a locking mechanism to prevent concurrent access to the Receipt object.

Even after adding this code, the application wouldn't be extensible for additional shared properties. The Shared Property Manager is another example of how Microsoft Transaction Server provides the infrastructure for server applications so that you can concentrate on coding business logic.

Location Transparency and the Shared Property Manager

For objects to share state, they all must be running in the same server process with the Shared Property Manager.

To maintain location transparency, it's a good idea to limit the use of a shared property group to objects created by the same component, or to objects created by components implemented within the same DLL. When components provided by different DLLs use the same shared property group, you run the risk of an administrator moving one or more of those components into a different package. Because components in different packages generally run in different processes, objects created by those components would no longer be able to share properties.

See Also

Resource Dispensers, Stateful Components, SharedPropertyGroupManager object


Stateful Components (Visual Basic)
Stateful Components

This section discusses stateful components and outlines some of the issues associated with writing stateful application components.

	Scenario: Holding State in the MoveMoney Component Consider the design alternative of holding state within objects.
	Adding a New Method to the MoveMoney Component Add the StatefulPerform method, which uses MoveMoney to maintain account number values.
	Application Design Notes: The Trade-offs of Using Stateful Objects Learn how holding state in objects affects the application behavior within the Microsoft Transaction Server run-time environment.
See Also

Transactions


Scenario: Holding State in the MoveMoney Component (Visual Basic)
Scenario: Holding State in the MoveMoney Component

Building stateful objects is a useful approach in application design. However, such design can have performance trade-offs. This section demonstrates how holding state in objects affects the application behavior within the Microsoft Transaction Server run-time environment.

You will modify the MoveMoney component to be stateful by adding the StatefulPerform function to MoveMoney. StatefulPerform is called when you click Stateful MoveMoney on the Sample Bank client. This new function causes MoveMoney to retain data in member variables between method calls.

See Also

Transactions, Deactivating Objects, Context Objects, Stateful Components


Adding a New Method to the MoveMoney Component (Visual Basic)
Adding a New Method to the MoveMoney Component

To implement the scenario for this section, you will add a method similar to Perform, named StatefulPerform, which uses class member variables to set account numbers. Thus, MoveMoney becomes a stateful object when StatefulPerform is called.

   To add a new function to the MoveMoney component

1	Open the \Mts\Samples\Account.VB\Step6\Account.vbp project.

Click here to see the StatefulPerform method

2	Build the component as a dynamic-link library (DLL) and save it as \Mts\Samples\Account.VB\Step6\VBAcct.dll.

The code for StatefulPerform calls the Perform method. The methods differ in how the account numbers are set. Class member variables for each account must be set before calling StatefulPerform, whereas Perform passes the account numbers by value through function parameters.

When you click the MoveMoney option in the Sample Bank client, it calls the following code to initialize the function:

StatefulPerform = Perform(PrimeAccount, SecondAccount, lngAmount, lngTranType)

When you click the Stateful MoveMoney option, the Sample Bank client calls the following code to initialize the function:

obj.PrimeAccount = PrimeAcct

obj.SecondAccount = lSecondAcct

Res = obj.StatefulPerform(CLng(Amount), TranType)

The PrimeAccount and SecondAccount properties are actually separate class member variables on the MoveMoney object. Note that the PrimeAccount and SecondAccount properties aren't accessed through the Shared Property Manager properties; the MoveMoney object controls getting and setting the account number values, thus making the MoveMoney object stateful.

Run the Bank client with the MoveMoney option. Then run it again with the Stateful MoveMoney option. You should notice that the stateless version is slightly faster. Try running multiple Bank clients with concurrent transactions. You should notice that the stateless version performs significantly better. The next section explains why.

See Also

Transactions, Deactivating Objects, Context Objects, Stateful Components


Application Design Notes: The Trade-offs of Using Stateful Objects (Visual Basic)
Application Design Notes: The Trade-offs of Using Stateful Objects

This section explains the trade-offs of using stateful objects in your applications.

Why does MoveMoney outperform Stateful MoveMoney?

In the previous section, you saw that the time per transaction in MoveMoney and Stateful MoveMoney using a single Sample Bank client is nearly the same. However, as the number of concurrent transactions increases, MoveMoney begins to outperform Stateful MoveMoney significantly . At first glance, the code doesn't seem to account for the lag.

Class member variables for each account must be set before calling StatefulPerform, whereas Perform passes the account numbers by value through function parameters. The call to return the value of the account number in the MoveMoney object isn't an intensive operation. So what explains the performance degradation?

The reason is that Microsoft Transaction Server cannot commit transactions until it completes a method call. To maintain internal state, additional method calls are made on the MoveMoney object, thereby delaying the object from completing its work. This delay may cause server resources, such as database connections, to be held longer, therefore decreasing the amount of resources available for other clients. In other words, the application won't scale well.

The following diagram illustrates this point. The arrow on the left indicates time, which translates into performance. The arrow on the right indicates the server resources consumed, which translates into throughput. Transaction A represents a call made to stateless objects. On return from the method call, Transaction Server determines that the transaction can be committed, allowing the object to release its resources and be deactivated. On the other hand, Transaction B holds state between method calls, which increases the time that the server holds onto resources for that transaction. As the number of clients increases, so does the time required for transactions to be completed.

Another Pitfall When Using Stateful Objects

Examine the following excerpt from the Sample Bank client code (some code has been omitted for clarity).

For i = 1 To nTrans

.

.

.

obj.PrimeAccount = PrimeAcct

obj.SecondAccount = lSecondAcct

Res = obj.StatefulPerform(CLng(Amount), TranType

.

.

.

Next i

Because the account numbers don't change, you might be inclined to rearrange the code as follows:

obj.PrimeAccount = PrimeAcct

obj.SecondAccount = lSecondAcct

For i = 1 To nTrans

Res = obj.StatefulPerform(CLng(Amount), TranType

Next i

If you modify the code and then run the Sample Bank client for multiple transactions, the application fails on the second transaction. Why?

The answer is subtle. MoveMoney uses SetComplete to notify Transaction Server that it has completed its work. At this point, the MoveMoney object is deactivated. In the process of deactivation, all of the object's member variables are reinitialized. The next call to MoveMoney causes just-in-time activation. The activated object is now in its initial state, meaning the values of PrimeAccountNo and SecondAccountNo are both zero. Thus, the next call to StatefulPerform fails because of an invalid account number.

This is yet another reason to be careful when maintaining state in objects. Clients of application objects must be aware of how an object uses SetComplete to ensure that any state the object maintains won't be needed after the object undergoes just-in-time activation.

See Also

Transactions, Deactivating Objects, Context Objects, Stateful Components, ObjectContext object, SetComplete method


Multiple Transactions (Visual Basic)
Multiple Transactions

This section explains the benefits of distributing work among multiple transactions.

	Scenario: Storing Receipt Numbers in a Database Add the UpdateReceipt component, which stores a maximum receipt number in a database and runs in a new transaction.
	Creating the UpdateReceipt Component Create the UpdateReceipt component, and modify the Receipt component to use UpdateReceipt.
	Application Design Notes: Using Separate Transactions Learn why this scenario requires separate transactions.
See Also

Transactions, Transaction Attributes, Activities


Scenario: Storing Receipt Numbers in a Database (Visual Basic)
Scenario: Storing Receipt Numbers in a Database

In Sharing State, you added the Receipt component, which assigns a unique receipt number to each monetary transaction. The Shared Property Manager maintains these values, so they exist for the duration of the server process. In this section, you will add code to store a maximum receipt number in a database. Storing them makes receipt numbers unique beyond the life of the server process.

You will create the UpdateReceipt component, which stores a maximum receipt number in a database. When this maximum is reached, which happens on every one-hundredth transaction, UpdateReceipt adds 100 to the maximum receipt value and updates the database.

You will install the UpdateReceipt component so that it creates a new transaction, separate from those of the Account objects. The section will then discuss the advantages of using multiple transactions in this scenario. The application looks like the following figure (the Shared Property Manager and its associated objects are omitted for clarity):

See Also

Transactions, Transaction Attributes, Activities, Sharing State


Creating the UpdateReceipt Component (Visual Basic)
Creating the UpdateReceipt Component

To implement the scenario for this section, you will build the UpdateReceipt component. You will also modify the Receipt component's Update method to use UpdateReceipt. Update adds 100 to the maximum receipt value stored in the database.

Click here to see the Update method

You also need to add code to the GetNextReciept method of the Receipt component to check whether the maximum receipt value has been reached. If so, the Update method is called.

Click here to see the GetNextReceipt method

To create the UpdateReceipt component

1	Open the \Mts\Samples\Account.VB\Step7\Account.vbp project.

2	Build the component as a dynamic-link library (DLL) and save it as \Mts\Samples\Account.VB\Step7\VBAcct.dll.

By adding a new class module, you add a new COM component to this DLL. Therefore, you need to delete the existing components in the Microsoft Transaction Server Explorer and then install the new components.

To reinstall your components

1	Remove the Account, MoveMoney, CreateTable, and Receipt components from the Transaction Server Explorer.

How?

2	Add the new components. Use the DLL you created in \Mts\Samples\Account.VB\Step7\VBAcct.dll.

How?

To set the transaction attributes for your components

1	For the Account and MoveMoney components, set the transaction attribute to Requires a transaction.

How?

2	For the Receipt component, set the transaction attribute to Does not support transactions. This is the default value.

3	For the CreateTable and UpdateReceipt components, set the transaction attribute to Requires a new transaction.

The code you added here is similar to the code you added in "Building Transactional Components." However, choosing Requires a new transaction causes the UpdateReceipt component to run in a new transaction. The next section discusses how this affects application behavior.

See Also

Transactions, Transaction Attributes


Application Design Notes: Using Separate Transactions (Visual Basic)
Application Design Notes: Using Separate Transactions

In Building Transactional Components, you saw the benefits of composing work under a transaction. The scenario in this section demonstrates a case in which using multiple transactions within an activity is required.

The major functional change in this scenario is the addition of the UpdateReceipt component, which makes the maximum receipt number durable by storing it in a database. As in Sharing State, the Shared Property Manager stores the receipt number. On every 100 transactions, the value in the database is incremented by 100. This dispenses a block of receipt numbers that are assigned to the next 100 transactions.

The UpdateReceipt component has a transaction attribute of Requires a new transaction. This guarantees that UpdateReceipt's work happens in a separate transaction. Thus, there is no connection between the success or failure of Account's work and UpdateReceipt's work.

This might appear to lower the fault tolerance of the application. For example, if the Account object aborts the transaction, a receipt number is still assigned. Therefore, skips in the receipt number sequence are possible. However, the application doesn't really need consecutively increasing receipt numbers--it just requires that there be no duplicate receipts. In this scenario, it's more important for the monetary transaction to be completed properly. Furthermore, requesting an update on every one-hundredth transaction improves performance by conserving calls to the database.

Composing both database updates under a single transaction would reduce the application's scalability. Even though UpdateReceipt is a simple update, it would consume more server resources because the database connection would have to be maintained until the Account object has completed its work. Thus, locks would be held longer than necessary, preventing other clients from writing to the database. Only when all work has been completed could these resources be freed.

See Also

Transactions, Transaction Attributes


Secured Components (Visual Basic)
Secured Components

This chapter shows how to use Microsoft Transaction Server's security features to restrict the use of application features to designated users.

	Scenario: Adding Role Checking to the MoveMoney and Account Components Add role checking to the MoveMoney and Account components to limit the transaction amount for designated users.
	Using IsCallerInRole in the MoveMoney and Account Components Use the IsCallerInRole method in the MoveMoney and Account components to verify that the user running the Bank client is a manager.
	Application Design Notes: Using Roles Learn how roles are useful in building secured components and how security boundaries are determined.
See Also

Programmatic Security


Scenario: Adding Role Checking to the MoveMoney and Account Components (Visual Basic)
Scenario: Adding Role Checking to the MoveMoney and Account Components

For this scenario, you will limit which users have the ability to perform transactions of more than $500. You will add code to the MoveMoney and Account components that checks to see if the user of the Bank client is a manager. This is accomplished by defining a Manager role. Roles provide the flexibility a developer needs to build secured components without tying the implementation to a specific deployment domain.

See Also

Programmatic Security, Application Design Notes: Using Roles


Using IsCallerInRole in the MoveMoney and Account Components (Visual Basic)
Using IsCallerInRole in the MoveMoney and Account Components

You will add the IsCallerInRole method to the MoveMoney and Account components to verify that the user running the Bank client is a manager. This additional code is the same for both components. You must modify both components because clicking Account in the Bank client doesn't use the MoveMoney component when the Sample Bank application runs.

To use IsCallerInRole in the MoveMoney and Account components

1	Open the \Mts\Samples\Account.VB\Step8\Account.vbp project.

Click here to see the modified MoveMoney component

Click here to see the modified Account component

2	Build the component as a DLL and save it as \Mts\Samples\Account.VB\Step8\VBAcct.dll.

IsCallerInRole is a method on an object's context. IsCallerInRole returns TRUE if the direct caller of that object is assigned to a given role. You will use IsCallerInRole in the MoveMoney and Account components to verify if the caller of an object — in this case the user running the Bank client — is a manager.

If (lngAmount > 500 Or lngAmount < -500) Then

    If Not GetObjectContext.IsCallerInRole("Managers") Then

        Err.Raise Number:=APP_ERROR, _

        Description:="Need 'Managers' role for amounts over $500"

    End If

End If

Before you can use the new MoveMoney and Account components, you must create the role. The Manager role must exist before the call to IsCallerInRole; otherwise, you will get an error.

Note that the source code is bound to a role name scoped to a package. This creates a dependancy between the source and the package definition that must be considered when making modifications to a Package's security configuration, such as deleting a role.

To define a role for the Sample Bank package

1	Start the Microsoft Transaction Server Explorer.

If you are currently running Sample Bank, you must shut down the associated server process to change security properties.

How?

2	Create a role named Manager.

How?

3	Assign users to the role. If you have access to more than one Windows NT account, you may want to exclude some user accounts from the Manager role to see the role checking in effect.

How?

Run the Bank client. If you are logged on as a user in the Manager role, you will be able to perform transactions of any amount. However, if you are logged on as a user who isn't in the Manager role, you will get a warning message when attempting a transaction of more than $500. The transaction will then abort. If you don't have access to more than one account, try removing your user account from the role to see the role checking enforced.

How?

See Also

Programmatic Security, Enabling MTS Package Security, Application Design Notes: Using Roles, IsCallerInRole method


Application Design Notes: Using Roles at Development Time (Visual Basic)
Application Design Notes: Using Roles

This section explains how roles are useful in building secured components. It also discusses how deployment configuration determines security boundaries.

Roles

A role is a symbolic name that defines a group of users for a package of components. Roles extend Windows NT security to allow a developer to build secured components in a distributed application. In this scenario, the Manager role is defined at development time, but not yet bound to specific users. For each deployment of the application, the administrator can then assign the users and groups to a role in order to customize the application for his or her business.

In this scenario, role checking is done by the MoveMoney and Account objects. When both MoveMoney and Account objects are used, the second check (on the Account object) is redundant. However, it yields the same result, because IsCallerInRole applies to the direct caller, and both the MoveMoney and Account objects run in the same server process.

If you place the MoveMoney and Account components into separate packages, the components run in separate server processes. In this scenario, calling IsCallerInRole on the Account object context would check if the MoveMoney object's associated server process is running in the Manager role. MoveMoney is now the direct caller because a process boundary has been crossed.

The Account object runs under a package identity that gives that process full access to the bank account database. Account objects have the authority to update any account for any amount. Roles provide a means of permitting and denying access to objects. Once this permission is granted, the client, in effect, has the same access rights as the server process.

When you configured the package, you chose a package identity of Interactive User. In a real-world scenario, packages are more likely to run as a specific user, such as SampleBank, which has access rights to the database.

Returning to the scenario where you split the MoveMoney and Account components into separate packages, running as the SampleBank user solves the role checking problem. Adding the SampleBank user to the Manager role would allow the second IsCallerInRole check (on the Account object) to always succeed.

Security Boundaries Are Process-Wide

Transaction Server security is enabled only within a server process. Because the MoveMoney component is configured to run within a server process, role checking is enabled.

If you configure the Sample Bank components to run in-process, role checking would be disabled. In this case, IsCallerInRole always returns TRUE, which means the direct caller would always pass the authorization check.

You could use the IsSecurityEnabled method to check if Transaction Server security can be used. IsSecurityEnabled returns FALSE when the object runs in-process. Using IsSecurityEnabled, you could rewrite the role-checking code to disable transactions when objects aren't running in a secured environment.

In-process components share the same level of trust as the base client. Because of this, it isn't recommended that you deploy your secured components to be loaded in-process with their clients.

See Also

Programmatic Security, Enabling MTS Package Security, IsCallerInRole method, IsSecurityEnabled method


Reference (Microsoft Transaction Server)
MTS Reference

Visual Basic

Functions

Methods

Objects

Properties

Language Summary

Visual C++

Functions

Interfaces

Methods

Language Summary

Visual J++

Interfaces

Methods

Language Summary


Functions (Visual Basic)

GetObjectContext

SafeRef


Objects (Visual Basic)

You use the following object in base clients:

TransactionContext

You use the following objects in components:

ObjectContext

SecurityProperty

SharedProperty

SharedPropertyGroup

SharedPropertyGroupManager


Methods (Visual Basic)

Abort

Activate

CanBePooled

Commit

Count

CreateInstance

CreateInstance (Transaction Context)

CreatePropertyGroup

CreateProperty

CreatePropertyByPosition

Deactivate

DisableCommit

EnableCommit

GetDirectCallerName

GetDirectCreatorName

GetOriginalCallerName

GetOriginalCreatorName

IsCallerInRole

IsInTransaction

IsSecurityEnabled

Item

SetAbort

SetComplete


Properties (Visual Basic)

Group

Property

PropertyByPosition

Value


Language Summary (Visual Basic)

Functions

GetObjectContext Function

SafeRef Function

ObjectContext Object

ObjectContext Object

ObjectContext Methods

Count

CreateInstance

DisableCommit

EnableCommit

IsCallerInRole

IsInTransaction

IsSecurityEnabled

Item

Security

SetAbort

SetComplete

ObjectControl Object

ObjectControl Object

ObjectControl Methods

Activate

CanBePooled

Deactivate

SecurityProperty Object

SecurityProperty Object

SecurityProperty Methods

GetDirectCallerName

GetDirectCreatorName

GetOriginalCallerName

GetOriginalCreatorName

SharedProperty Object

SharedProperty Object

SharedProperty Properties

Value

SharedPropertyGroup Object

SharedPropertyGroup Object

SharedPropertyGroup Properties and Methods

CreateProperty

CreatePropertyByPosition

Property

PropertyByPosition

SharedPropertyGroupManager Object

SharedPropertyGroupManager Object

SharedPropertyGroupManager Methods

CreatePropertyGroup

Group

TransactionContext Object

TransactionContext Object

TransactionContext Methods

Abort

Commit

CreateInstance


Functions (Visual C++)

GetObjectContext

SafeRef


Interfaces (Visual C++)

You use the following object in base clients:

ITransactionContext

You use the following objects in components:

IGetContextProperties

IObjectContext

IObjectContextActivity

IObjectControl

ISecurityProperty

ISharedProperty

ISharedPropertyGroup

ISharedPropertyGroupManager


Methods (Visual C++)

Abort

Activate

CanBePooled

Commit

Count

CreateInstance

CreateInstance (Transaction Context)

CreatePropertyGroup

CreateProperty

CreatePropertyByPosition

Deactivate

DisableCommit

EnableCommit

EnumNames

get__NewEnum

get_Group

get_Property

get_PropertyByPosition

get_Value

GetActivityId

GetDirectCallerSID

GetDirectCreatorSID

GetOriginalCallerSID

GetOriginalCreatorSID

GetProperty

IsCallerInRole

IsInTransaction

IsSecurityEnabled

put_Value

ReleaseSID

SetAbort

SetComplete


Language Summary (Visual C++)

Functions

GetObjectContext Function

SafeRef Function

IGetContextProperties Interface

IGetContextProperties Interface

IGetContextProperties Methods

Count

EnumNames

GetProperty

IObjectContext Interface

IObjectContext Interface

IObjectContext Methods

CreateInstance

DisableCommit

EnableCommit

IsCallerInRole

IsInTransaction

IsSecurityEnabled

SetAbort

SetComplete

IObjectContextActivity Interface

IObjectContextActivity Interface

IObjectContextActivity Methods

IObjectContextActivity::GetActivityId Method

IObjectControl Interface

IObjectControl Interface

IObjectControl Interface Methods

Activate

CanBePooled

Deactivate

ISecurityProperty Interface

ISecurityProperty Interface

ISecurityProperty Interface Methods

GetDirectCallerSID

GetDirectCreatorSID

GetOriginalCallerSID

GetOriginalCreatorSID

ReleaseSID

ISharedProperty Interface

ISharedProperty Interface

ISharedProperty Interface Methods

put_Value

get_Value

ISharedPropertyGroup Interface

ISharedPropertyGroup Interface

ISharedPropertyGroup Methods

CreateProperty

CreatePropertyByPosition

get_Property

get_PropertyByPosition

ISharedPropertyGroupManager Interface

ISharedPropertyGroupManager Interfacea

ISharedPropertyGroupManager Methods

CreatePropertyGroup

get_Group

get__NewEnum

ITransactionContextEx Interface

ITransactionContextEx Interface

ITransactionContextEx Methods

Abort

Commit

CreateInstance


Interfaces (Visual J++)

You use the following object in base clients:

ITransactionContext

You use the following objects in components:

IGetContextProperties

IObjectContext

IObjectControl

ISharedProperty

ISharedPropertyGroup

ISharedPropertyGroupManager


Methods (Visual J++)

Abort

Activate

CanBePooled

Commit

Count

CreateInstance

CreateInstance (Transaction Context)

CreatePropertyGroup

CreateProperty

CreatePropertyByPosition

Deactivate

DisableCommit

EnableCommit

EnumNames

get_NewEnum

getGroup

getProperty

GetProperty

getPropertyByPosition

getValue

IsCallerInRole

IsInTransaction

IsSecurityEnabled

MTx.GetObjectContextasfctGetObjectContextvj

MTx.SafeRef

putValueasmthPutValuevj

SetAbort

SetComplete


Language Summary (Visual J++)

Context Class

Context Class

Context Methods

createInstance

disableCommit

enableCommit

getPropertyNames

getProperty

isCallerInRole

isInTransaction

isSecurityEnabled

setAbort

setComplete

Mtx.GetObjectContext

MTx.GetObjectContext

MTx.GetObjectContext Method

MTx.SafeRef Method

IGetContextProperties Interface

IGetContextProperties Interface

IGetContextProperties Methods

Count

EnumNames

GetProperty

IObjectContext Interface

IObjectContext Interface

IObjectContext Methods

CreateInstance

DisableCommit

EnableCommit

IsCallerInRole

IsInTransaction

IsSecurityEnabled

SetAbort

SetComplete

IObjectControl Interface

IObjectControl Interface

IObjectControl Methods

Activate

CanBePooled

Deactivate

ISharedProperty Interface

ISharedProperty Interface

ISharedProperty Methods

putValue

getValue

ISharedPropertyGroup Interface

ISharedPropertyGroup Interface

ISharedPropertyGroup Methods

CreateProperty

CreatePropertyByPosition

getProperty

getPropertyByPosition

ISharedPropertyGroupManager Interface

ISharedPropertyGroupManager Interface

ISharedPropertyGroupManager Methods

CreatePropertyGroup

getGroup

get_NewEnum

ITransactionContextEx Interface

ITransactionContextEx Interface

ITransactionContextEx Methods

Abort

Commit

CreateInstance


IGetContextProperties Interface (Visual C++)
IGetContextProperties Interface

The IGetContextProperties interface provides access to context object properties.

Remarks

The header file for the IGetContextProperties interface is mtx.h.

The IGetContextProperties interface exposes the following methods.

Method	Description
Count	Returns the number of properties associated with the context object.
EnumNames	Returns a reference to an enumerator that you can use to iterate through all the context object properties.
GetProperty	Returns a context object property.
See Also

Context Objects


IGetContextProperties::Count Method (Visual C++)
IGetContextProperties::Count Method

Returns the number of context object properties.

Provided By

IGetContextProperties

HRESULT IGetContextProperties::Count (
long * plCount);

Parameters

plCount
[out] The number of properties.

Return Values

S_OK
A valid count is returned in the plCount parameter.

E_INVALIDARG
The valid count could not be returned.

Example


IGetContextProperties::EnumNames Method (Visual C++)
IGetContextProperties::EnumNames Method

Returns a reference to an enumerator that you can use to iterate through all the context object properties.

Provided By

IGetContextProperties

HRESULT IGetContextProperties::EnumNames (

IEnumNames ** ppenum);

Parameters

ppenum
[out] A reference to the IEnumNames interface on a new enumerator object that you can use to iterate through all the context object properties.

Return Values

S_OK
A reference to the requested enumerator is returned in the ppenum parameter.

E_INVALIDARG
The requested enumerator could not be returned.

Remarks

You use the EnumNames method to obtain a reference to an enumerator object. The returned IEnumNames interface exposes several methods you can use to iterate through a list of BSTRs representing context object properties. Once you have a name, you can use the GetProperty method to obtain a reference to the context object property it represents. See the COM documentation for information on enumerators.

As with any COM object, you must release an enumerator object when you're finished using it.

Example


IGetContextProperties::GetProperty Method (Visual C++)
IGetContextProperties::GetProperty Method

Returns a context object property.

Provided By

IGetContextProperties

HRESULT IGetContextProperties::GetProperty (
BSTR	name
VARIANT *	pProperty);

Parameters

name
[in] The name of the context object property to be retrieved.

pProperty
[out] The returned pointer to the property.

Return Values

S_OK
The property was returned successfully.

S_FALSE
The property was not found.

E_INVALIDARG
The name parameter was invalid.

Remarks

You can use GetProperty to retrieve the following Microsoft Internet Information Server (IIS) intrinsic objects:

•	Request

•	Response

•	Server

•	Application

•	Session

For more information, see the IIS documentation.

To retrieve an IIS object, call QueryInterface using the VT_DISPATCH member of the returned VARIANT for the interface to the IIS object (for example IReponse for the Response object).

Note   Context properties are not available in MTS 1.0 server processes.

Example


Count, EnumNames, GetProperty Methods Example (Visual C++)
Count, EnumNames, GetProperty Methods Example

#include "stdafx.h"

#include <initguid.h>

#include "asptlb.h"

#include "mtx.h"

HRESULT hr = NOERROR;

// Get the context object

CComPtr<IObjectContext> pObjectContext;

hr = GetObjectContext(&pObjectContext);

// Get the Response object

CComVariant v;

CComBSTR bstr(L"Response");

CComQIPtr<IGetContextProperties, 	&IID_IGetContextProperties> pProps(pObjectContext);

hr = pProps->GetProperty(bstr, &v);

CComPtr<IDispatch> pDisp;

pDisp = V_DISPATCH(&v);

CComQIPtr<IResponse, &IID_IResponse> pResponse(pDisp);

// Print number of properties

long lCount;

hr = pProps->Count(&lCount);

bstr = L"<p>Number of properties: ";

CComBSTR bstrCount;

VarBstrFromI4(lCount, 0, 0, &bstrCount);

bstr.Append(bstrCount);

bstr.Append(L"</p>");

v = bstr;

hr = pResponse->Write(v);

// Iterate over properties collection and print the

// names of the properties

CComPtr<IEnumNames> pEnum;

CComBSTR bstrTemp;

pProps->EnumNames(&pEnum);

for ( int i = 0; i < lCount; ++i )

{

pEnum->Next(1, &bstr, NULL);

bstrTemp = L"<p>";

bstrTemp.Append(bstr);

bstrTemp.Append(L"</p>");

v = bstrTemp;

hr = pResponse->Write(v);

}


IGetContextProperties Interface (Visual J++)
IGetContextProperties Interface

The IGetContextProperties interface provides access to context object properties.

Remarks

New applications should use the Context class.

The IGetContextProperties interface is declared in the package com.ms.mtx.

The IGetContextProperties interface exposes the following methods.

Method	Description
Count	Returns the number of properties associated with the context object.
EnumNames	Returns a reference to an enumerator that you can use to iterate through all the context object properties.
GetProperty	Returns a context object property.
See Also

Context Objects


IGetContextProperties.Count Method (Visual J++)
IGetContextProperties.Count Method

Returns the number of context object properties.

Provided By

IGetContextProperties

int Count( );

Return Value

The number of properties.

Example


IGetContextProperties.EnumNames Method (Visual J++)
IGetContextProperties.EnumNames Method

Returns a reference to an enumerator that you can use to iterate through all the context object properties.

New applications should call getPropertyNames.

Provided By

IGetContextProperties

IEnumNames EnumNames ( );

Return Value

A reference to the IEnumNames interface on a new enumerator object that you can use to iterate through the list of all the shared property groups in the process.

Remarks

You use the EnumNames method to obtain a reference to an enumerator object. The returned IEnumNames interface exposes several methods you can use to iterate through a list of string expressions representing context object properties. Once you have a name, you can use the GetProperty method to obtain a reference to the context object property it represents. See the COM documentation for information on enumerators.

Example


IGetContextProperties.GetProperty Method (Visual J++)
IGetContextProperties.GetProperty Method

Returns a context object property.

New applications should call getProperty.

Provided By

IGetContextProperties

Variant GetProperty(
String name);

Parameters

name
[in] The name of the context object property to be retrieved.

Return Value

The requested context object property.

Remarks

You can use GetProperty to retrieve the following Microsoft Internet Information Server (IIS) intrinsic objects:

•	Request

•	Response

•	Server

•	Application

•	Session

For more information, see the IIS documentation.

To retrieve an IIS object, use the getDispatch method of returned Variant and cast this value to the interface to the IIS object (for example IReponse for the Response object).

Note   Context properties are not available in MTS 1.0 server processes.

Example


Count, EnumNames, GetProperty Methods Example (Visual J++)
Count, EnumNames, GetProperty Methods Example

import com.ms.com.*;

import com.ms.mtx.*;

import asp.*;

// Get the context object

IGetContextProperties icp;

IResponse iresp;

Variant av = new Variant();

icp = (IGetContextProperties)MTx.GetObjectContext();

// Get the Response object

av = icp.GetProperty("Response");

iresp = (IResponse) av.getDispatch();

av.VariantClear();

// Print number of properties

String str;

int pc;

pc = icp.Count();

str = "<p>Number of properties: " + pc + "</p>";

av.putString(str);

iresp.Write (av);

av.VariantClear();

// Iterate over properties collection and print the

// names of the properties

IEnumNames iEnum = null;

int howmany = 1;

String[] names = new String[1];

int fetched;

iEnum = icp.EnumNames();

for ( int i = 0; i < pc; ++i )

{

fetched = iEnum.Next( howmany, names);

str = "<p>" + names[0] + "</p>";

av.putString(str);

iresp.Write (av);

av.VariantClear();

}


ObjectControl Object (Visual Basic)
ObjectControl Object

You implement the ObjectControl interface when you want to define context-specific initialization and cleanup procedures for your MTS objects and specify whether or not the objects can be recycled. Implementing the ObjectControl interface is optional.

Remarks

To use the ObjectControl object, you must set a reference to the Microsoft Transaction Server Type Library (MTxAS.dll).

If you implement the ObjectControl interface in your component, the MTS run-time environment automatically calls the ObjectControl methods on your objects at the appropriate times.

When an object supports the ObjectControl interface, MTS calls its Activate method once for each time the object is activated. The Activate method is called before any of the object's other methods are called. You can use this method to perform any context-specific initialization an object may require.

MTS calls the object's Deactivate method each time the object is deactivated. This can be the result of the object returning from a method in which it calls SetComplete or SetAbort, or due to the root of the object's transaction, causing the transaction to complete. You use the Deactivate method to clean up state that you initialized in the Activate method.

After calling the Deactivate method, the MTS run-time environment calls the CanBePooled method. If this method returns True, the deactivated object is placed in an object pool for reuse. If the CanBePooled method returns False, the object is released in the usual way.

Note   On systems that don't support object pooling, the value returned by this method is ignored.

The ObjectControl interface is not accessible to an object's clients or to the object itself. Only the MTS run-time environment can invoke the ObjectControl methods.

The ObjectControl interface provides the following methods.

Method	Description
Activate	Allows an object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.
CanBePooled	Allows an object to notify the MTS run-time environment of whether it can be pooled for reuse. Return True if you want instances of this component to be pooled, or False if not.
Deactivate	Allows an object to perform whatever cleanup is necessary before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.
See Also

Deactivating Objects, Object Pooling and Recycling


Activate Method (Visual Basic)
Activate Method

Implementing this method allows an MTS object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.

Applies To

ObjectContext Object

Syntax

objectcontrol.Activate

The objectcontrol placeholder represents is an object variable that evaluates to an ObjectControl object.

Remarks

To use the ObjectControl object, you must set a reference to the Microsoft Transaction Server Type Library (MTxAS.dll).

Whenever a client calls an MTS object that isn't already activated, the MTS run-time environment automatically activates the object. This is called just-in-time activation. For components that support the ObjectControl interface, MTS invokes the object's Activate  method before passing the client's method call on to the object. This allows objects to do context-specific initialization.

If you need to perform any initialization that involves the ObjectContext, you should implement the Activate method and place all your context-specific initialization procedures there.

For example, you can use the Activate method to obtain a reference to an object's context and store it in a member variable. Then the context  is available to any method that requires it, and you don't have to acquire a new one and then release it every time you use it. Once you have a reference to the object's context, you can use the IObjectContext methods to check whether security is enabled, whether the object is executing in a transaction, or whether the caller is in a particular role.

If you're enabling object recycling (returning True from the CanBePooled method), the Activate method must be able to handle both newly created and recycled objects. When the Activate method returns, there should be no distinguishable difference between a new object and a recycled one.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


Activate Method Example (Visual Basic)
Activate Method Example

Implements ObjectControl

Dim context As ObjectContext

Option Explicit

Private Sub ObjectControl_Activate()

' Get a reference to the object's context here,

' so it can be used by any method that may be

' called during this activation of the object.

Set context = GetObjectContext()

End Sub


CanBePooled Method (Visual Basic)
CanBePooled Method

Implementing this method allows an MTS object to notify the MTS run-time environment of whether it can be pooled for reuse. Return True if you want the object to be pooled for reuse, or False if not.

Applies To

ObjectContext Object

Syntax

objectcontrol.CanBePooled (True | False)

The objectcontrol placeholder represents is an object variable that evaluates to an ObjectControl object.

Return Values

True
Notifies the MTS run-time environment that it can pool this object on deactivation for later reuse.

False
Notifies the MTS run-time environment that it should not pool this object on deactivation, but should release its last reference to the object so that the object will be destroyed.

Remarks

To use the ObjectControl object, you must set a reference to the Microsoft Transaction Server Type Library (MTxAS.dll).

When an object returns True from the CanBePooledmethod, it indicates to the MTS run-time environment that it can be added to an object pool after deactivation rather than being destroyed. Whenever an instance is required, one is drawn from the pool rather than created.

The way recycling works is that an object cleans itself up in its Deactivate method and is returned to an object pool. Later, when an instance of the same component is needed, the cleaned up object can be reused. For this to work, an object must be accessible on different threads each time it's activated. Recycling isn't possible under the apartment threading model because, in that model, although an object can be instantiated on any thread, it can only be used by the thread on which it was instantiated. If you want instances of a component to be recyclable, you should register the component with the ThreadingModel Registry value set to Both. This indicates to MTS that the component's objects can be called from different threads.

In MTS, these objects will run under the apartment threading model and won't be recycled even if they return True from the CanBePooled method. However, if you configure a component to support both threading models, the component will run under the current version of MTS and will also be able to take advantage of recycling as soon as it becomes available, without any changes to the code.

Deciding whether to enable recycling is a matter of weighing the costs and benefits. Recycling requires writing additional code, and there's a risk that some state may be inadvertently retained from one activation to the next. When you allow objects to be pooled, you have to be very careful in your Activate  and Deactivate methods to ensure that a recycled object is always restored to a state that's equivalent to the state of a newly created object. Another consideration to take into account is the amount of resources required to maintain an object pool. Objects that hold a lot of resources can be expensive to pool. However, in certain situations, recycling can be extremely efficient, resulting in improved performance and increased scalability. The trade-off is between the cost of holding onto resources while objects are pooled (and inactive) versus the cost of creating and destroying the resources.

It's usually best to enable recycling for objects that cost more to create than they cost to reinitialize. For example, if a component contains a complex structure, and that structure can be reused, it could save a lot of time if the structure didn't have to be recreated every time an instance of the component was activated. This is a case in which you might want to enable recycling, which you would do by returning True from the CanBePooled method.

The Activate method is called whether a new instance is created or a recycled instance is drawn from the pool. Similarly, the Deactivate method is called every time the object is deactivated, whether it's being destroyed or returned to the pool for recycling.

So, in this example, you'd use the object's Activate method to initialize, or reinitialize, the structure that's being reused, and you'd use the Deactivate method to restore the object to a state that the Activate method can handle. (The Activate method must be able to handle both new objects and reused objects drawn from the pool.) This combined use of the Activate, Deactivate, and CanBePooled methods eliminates the need to recreate reusable resources every time an instance is activated.

For some objects, recycling isn't efficient. For example, if an object acquires a lot of state during its lifetime that isn't reusable, and has little to do during its construction, it's usually cheaper to create a new instance whenever one is needed. In that case, you would return False from the CanBePooled method.

Note   Returning True from the CanBePooled method doesn't guarantee that objects will be recycled; it only gives the MTS run-time environment permission to recycle them. On systems that don't support object pooling, a return value of True is ignored. Returning False from the CanBePooled method guarantees that instances of a component aren't recycled.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


CanBePooled Method Example (Visual Basic)
CanBePooled Method Example

Implements ObjectControl

Dim context As ObjectContext

Option Explicit

Private Function ObjectControl_CanBePooled() As Boolean

' This object should not be recycled,

' so return false.

ObjectControl_CanBePooled = False

End Function


Deactivate Method (Visual Basic)
Deactivate Method

Implementing this method allows an MTS object to perform any cleanup required before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.

Applies To

ObjectContext Object

Syntax

objectcontrol.Deactivate

The objectcontrol placeholder represents is an object variable that evaluates to an ObjectControl object.

Remarks

To use the ObjectControl object, you must set a reference to the Microsoft Transaction Server Type Library (MTxAS.dll).

The MTS run-time environment calls the Deactivate method whenever an object that supports the ObjectControl interface is deactivated. An object is deactivated when it returns from a method in which it called SetComplete or SetAbort, when the transaction in which it executed is committed or aborted, or when the last client to hold a reference on it releases its reference.

If the component supports recycling (returns True from the CanBePooled method), you should use the Deactivate method to reset the object's state to the state in which the Activate method expects to find it. You can also use the Deactivate method to release the object's ObjectContext or to do other context-specific cleanup. Even if an object supports recycling, it can be beneficial to release certain reusable resources in its Deactivate method. For example, ODBC provides its own connection pooling. It's more efficient to pool a database connection in a general connection pool where it can be used by other objects than it is to keep it tied to a specific object in an object pool.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


Deactivate Method Example (Visual Basic)
Deactivate Method Example

Implements ObjectControl

Dim objcontext As ObjectContext

Option Explicit

Private Sub ObjectControl_Deactivate()

' Perform any necessary cleanup here.

Set objcontext = Nothing

End Sub


IObjectControl Interface (Visual C++)
IObjectControl Interface

You implement the IObjectControl interface when you want to define context-specific initialization and cleanup procedures for your MTS objects and specify whether or not the objects can be recycled. Implementing the IObjectControl interface is optional.

Remarks

The header file for the IObjectControl interface is mtx.h.

If you implement the IObjectControl interface in your component, the MTS run-time environment automatically calls the IObjectControl methods on your objects at the appropriate times.

When an object supports the IObjectControl interface, MTS calls its Activate method once for each time the object is activated. The Activate method is called before any of the object's other methods are called. You can use this method to perform any context-specific initialization an object may require.

Note   An object's context isn't available during object construction (from the object's class factory), so context-specific initialization can't be performed in an object's constructor.

MTS calls the object's Deactivate method each time the object is deactivated. This can be the result of the object returning from a method in which it calls SetComplete or SetAbort, or due to the root of the object's transaction, causing the transaction to complete. You use the Deactivate method to clean up state that you initialized in the Activate method.

After calling the Deactivate method, the MTS run-time environment calls the CanBePooled method. If this method returns TRUE, the deactivated object is placed in an object pool for reuse. If the CanBePooled method returns FALSE, the object is released in the usual way and its destructor is invoked.

Note   On systems that don't support object pooling, the value returned by this method is ignored.

The IObjectControl interface is not accessible to an object's clients or to the object itself. Only the MTS run-time environment can invoke the IObjectControl methods. If a client queries for the IObjectControl interface, QueryInterface will return E_NOINTERFACE.

The IObjectControl interface exposes the following methods.

Method	Description
Activate	Allows an object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.
CanBePooled	Allows an object to notify the MTS run-time environment of whether it can be pooled for reuse. Return TRUE if you want instances of this component to be pooled, or FALSE if not.
Deactivate	Allows an object to perform whatever cleanup is necessary before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.
See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl::Activate Method (Visual C++)
IObjectControl::Activate Method

Implementing this method allows an MTS object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.

Provided By

IObjectContext

HRESULT IObjectControl::Activate ( );

Return Values

S_OK
The Activate method succeeded.

Failure HRESULT
Any error code indicating why an object was unable to activate itself.

Remarks

Whenever a client calls an MTS object that isn't already activated, the MTS run-time environment automatically activates the object. This is called just-in-time activation. For components that support the IObjectControl interface, MTS invokes the object's Activate method before passing the client's method call on to the object. This allows objects to do context-specific initialization.

Because an object's context isn't available during object construction, you can't perform any initialization that involves the ObjectContextinside the constructor. Instead, you should implement the Activate method and place all your context-specific initialization procedures there.

For example, you can use the Activate method to obtain a reference to an object's context and store it in a member variable. Then the context reference is available to any method that requires it, and you don't have to acquire a new one and then release it every time you use it. Once you have a reference to the object's context, you can use the IObjectContext methods to check whether security is enabled, whether the object is executing in a transaction, or whether the caller is in a particular role. You can also use the Activate method to obtain a reference to the object's SecurityProperty and check the security ID of the object's creator before any methods are called.

If you're enabling object recycling (returning TRUE from the CanBePooled method), the Activate method must be able to handle both newly created and recycled objects. When the Activate method returns, there should be no distinguishable difference between a new object and a recycled one.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl::Activate Method Example (Visual C++)
IObjectControl::Activate Method Example

#include <mtx.h>

IObjectContext* m_pObjectContext;

HRESULT MyObject::Activate()

{

// Get a reference to the object's context here,

// so it can be used by any method that may be

// called during this activation of the object.

HRESULT hr = GetObjectContext(&m_pObjectContext);

if (SUCCEEDED(hr))

return S_OK;

return hr;

}


IObjectControl::CanBePooled Method (Visual C++)
IObjectControl::CanBePooled Method

Implementing this method allows an MTS object to notify the MTS run-time environment of whether it can be pooled for reuse. Return TRUE if you want the object to be pooled for reuse, or FALSE if not.

Provided By

IObjectContext

BOOL IObjectControl::CanBePooled ( );

Return Values

TRUE
Notifies the MTS run-time environment that it can pool this object on deactivation for later reuse.

FALSE
Notifies the MTS run-time environment that it should not pool this object on deactivation, but should release its last reference to the object so that the object will be destroyed.

Remarks

When an object returns TRUE from the CanBePooledmethod, it indicates to the MTS run-time environment that it can be added to an object pool after deactivation rather than being destroyed. Whenever an instance is required, one is drawn from the pool rather than created by the class factory.

The way recycling works is that an object cleans itself up in its Deactivate method and is returned to an object pool. Later, when an instance of the same component is needed, the cleaned up object can be reused. For this to work, an object must be accessible on different threads each time it's activated. Recycling isn't possible under the apartment threading model because, in that model, although an object can be instantiated on any thread, it can only be used by the thread on which it was instantiated. If you want instances of a component to be recyclable, you should register the component with the ThreadingModel Registry value set to Both. This indicates to MTS that the component's objects can be called from different threads.

In MTS, these objects will run under the apartment threading model and won't be recycled even if they return TRUE from the CanBePooled method. However, if you configure a component to support both threading models, the component will run under the current version of MTS and will also be able to take advantage of recycling as soon as it becomes available, without any changes to the code.

Deciding whether to enable recycling is a matter of weighing the costs and benefits. Recycling requires writing additional code, and there's a risk that some state may be inadvertently retained from one activation to the next. When you allow objects to be pooled, you have to be very careful in your Activate and Deactivate methods to ensure that a recycled object is always restored to a state that's equivalent to the state of a newly created object. Another consideration to take into account is the amount of resources required to maintain an object pool. Objects that hold a lot of resources can be expensive to pool. However, in certain situations, recycling can be extremely efficient, resulting in improved performance and increased scalability. The trade-off is between the cost of holding onto resources while objects are pooled (and inactive) versus the cost of creating and destroying the resources.

It's usually best to enable recycling for objects that cost more to create than they cost to reinitialize. For example, if a component contains a complex structure, and that structure can be reused, it could save a lot of time if the structure didn't have to be recreated every time an instance of the component was activated. This is a case in which you might want to enable recycling, which you would do by returning TRUE from the CanBePooled method.

You could still create the structure in the object's constructor and release it in the destructor. The constructor is only called once, when a new object is created by the class factory. When recycling is enabled, that only happens when the object pool is empty. The Activate method, on the other hand, is called whether a new instance is created by the class factory or a recycled instance is drawn from the pool. Similarly, the object's destructor is only called when no further instances are needed, for example, when the server is shutting down. The Deactivate method is called every time the object is deactivated, whether it's being destroyed or returned to the pool for recycling.

So, in this example, you'd use the object's Activate method to initialize, or reinitialize, the structure that's being reused, and you'd use the Deactivate method to restore the object to a state that the Activate method can handle. (The Activate method must be able to handle both new objects created by the class factory and reused objects drawn from the pool.) This combined use of the Activate, Deactivate, and CanBePooled methods eliminates the need to recreate reusable resources every time an instance is activated.

For some objects, recycling isn't efficient. For example, if an object acquires a lot of state during its lifetime that isn't reusable, and has little to do during its construction, it's usually cheaper to create a new instance whenever one is needed. In that case, you would return FALSE from the CanBePooled method.

Note   Returning TRUE from the CanBePooled method doesn't guarantee that objects will be recycled; it only gives the MTS run-time environment permission to recycle them. On systems that don't support object pooling, a return value of TRUE is ignored. Returning FALSE from the CanBePooled method guarantees that instances of a component aren't recycled.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl::CanBePooled Method Example (Visual C++)
IObjectControl::CanBePooled Method Example

#include <mtx.h>

BOOL MyObject::CanBePooled()

{

// This object should not be recycled,

// so return false.

return FALSE;

}


IObjectControl::Deactivate Method (Visual C++)
IObjectControl::Deactivate Method

Implementing this method allows an MTS object to perform any cleanup required before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.

Provided By

IObjectContext

void IObjectControl::Deactivate ( );.

Remarks

The MTS run-time environment calls the Deactivate method whenever an object that supports the IObjectControl interface is deactivated. An object is deactivated when it returns from a method in which it called SetComplete or SetAbort, when the transaction in which it executed is committed or aborted, or when the last client to hold a reference on it releases its reference.

If the component supports recycling (returns TRUE from the CanBePooled method), you should use the Deactivate method to reset the object's state to the state in which the Activatemethod expects to find it. You can also use the Deactivate method to release the object's ObjectContext reference or to do other context-specific cleanup. You can't do this in the Release method or the destructor, because the IObjectContext interface isn't accessible from the destructor or any of the IUnknown methods. Even if an object supports recycling, it can be beneficial to release certain reusable resources in its Deactivate method. For example, ODBC provides its own connection pooling. It's more efficient to pool a database connection in a general connection pool where it can be used by other objects than it is to keep it tied to a specific object in an object pool.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl::Deactivate Method Example (Visual C++)
IObjectControl::Deactivate Method Example

#include <mtx.h>

void MyObject::Deactivate(void)

{

// This object is no longer associated with this

// context, so release the reference it acquired in

// its Activate method.

m_pObjectContext->Release();

}


IObjectControl Interface (Visual J++)
IObjectControl Interface

You implement the IObjectControl interface when you want to define context-specific initialization and cleanup procedures for your MTS objects and specify whether or not the objects can be recycled. Implementing the IObjectControl interface is optional.

Remarks

The IObjectControl interface is declared in the package com.ms.mtx.

If you implement the IObjectControl interface in your component, the MTS run-time environment automatically calls the IObjectControl methods on your objects at the appropriate times.

When an object supports the IObjectControl interface, MTS calls its Activate method once for each time the object is activated. The Activate method is called before any of the object's other methods are called. You can use this method to perform any context-specific initialization an object may require.

Note   An object's context isn't available during object construction (from the object's class factory), so context-specific initialization can't be performed in an object's constructor.

MTS calls the object's Deactivate method each time the object is deactivated. This can be the result of the object returning from a method in which it calls SetComplete or SetAbort, or due to the root of the object's transaction, causing the transaction to complete. You use the Deactivate method to clean up state that you initialized in the Activate method.

After calling the Deactivate method, the MTS run-time environment calls the CanBePooled method. If this method returns true, the deactivated object is placed in an object pool for reuse. If the CanBePooled method returns false, the object is released in the usual way.

Note   On systems that don't support object pooling, the value returned by this method is ignored.

The IObjectControl interface is not accessible to an object's clients or to the object itself. Only the MTS run-time environment can invoke the IObjectControl methods.

The IObjectControl interface exposes the following methods.

Method	Description
Activate	Allows an object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.
CanBePooled	Allows an object to notify the MTS run-time environment of whether it can be pooled for reuse. Return true if you want instances of this component to be pooled, or false if not.
Deactivate	Allows an object to perform whatever cleanup is necessary before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.
See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl.Activate Method (Visual J++)
IObjectControl.Activate Method

Implementing this method allows an MTS object to perform context-specific initialization whenever it's activated. This method is called by the MTS run-time environment before any other methods are called on the object.

Provided By

IObjectContext

void Activate ( );

Remarks

Whenever a client calls an MTS object that isn't already activated, the MTS run-time environment automatically activates the object. This is called just-in-time activation. For components that support the IObjectControl interface, MTS invokes the object's Activate method before passing the client's method call on to the object. This allows objects to do context-specific initialization.

Because an object's context isn't available during object construction, you can't perform any initialization that involves the ObjectContextinside the constructor. Instead, you should implement the Activate method and place all your context-specific initialization procedures there.

For example, you can use the Activate method to obtain a reference to an object's context and store it in a member variable. Then the context reference is available to any method that requires it, and you don't have to acquire a new one and then release it every time you use it. Once you have a reference to the object's context, you can use the IObjectContext methods to check whether security is enabled, whether the object is executing in a transaction, or whether the caller is in a particular role.

If you're enabling object recycling (returning true from the CanBePooled method), the Activate method must be able to handle both newly created and recycled objects. When the Activate method returns, there should be no distinguishable difference between a new object and a recycled one.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl.Activate Method Example (Visual J++)
IObjectControl.Activate Method Example

import com.ms.mtx.*;

void Activate()

{

// Get a reference to the object's context here,

// so it can be used by any method that may be

// called during this activation of the object.

m_ObjectContext = MTx.GetObjectContext()

}


IObjectControl.CanBePooled Method (Visual J++)
IObjectControl.CanBePooled Method

Implementing this method allows an MTS object to notify the MTS run-time environment of whether it can be pooled for reuse. Return true if you want the object to be pooled for reuse, or false if not.

Provided By

IObjectContext

boolean CanBePooled ( );

Return Values

true
Notifies the MTS run-time environment that it can pool this object on deactivation for later reuse.

false
Notifies the MTS run-time environment that it should not pool this object on deactivation, but should release its last reference to the object so that the object will be destroyed.

Remarks

When an object returns true from the CanBePooledmethod, it indicates to the MTS run-time environment that it can be added to an object pool after deactivation rather than being destroyed. Whenever an instance is required, one is drawn from the pool rather than created by the class factory.

The way recycling works is that an object cleans itself up in its Deactivate method and is returned to an object pool. Later, when an instance of the same component is needed, the cleaned up object can be reused. For this to work, an object must be accessible on different threads each time it's activated. Recycling isn't possible under the apartment threading model because, in that model, although an object can be instantiated on any thread, it can only be used by the thread on which it was instantiated. If you want instances of a component to be recyclable, you should register the component with the ThreadingModel Registry value set to Both. This indicates to MTS that the component's objects can be called from different threads.

In MTS, these objects will run under the apartment threading model and won't be recycled even if they return true from the CanBePooled method. However, if you configure a component to support both threading models, the component will run under the current version of MTS and will also be able to take advantage of recycling as soon as it becomes available, without any changes to the code.

Deciding whether to enable recycling is a matter of weighing the costs and benefits. Recycling requires writing additional code, and there's a risk that some state may be inadvertently retained from one activation to the next. When you allow objects to be pooled, you have to be very careful in your Activate and Deactivate methods to ensure that a recycled object is always restored to a state that's equivalent to the state of a newly created object. Another consideration to take into account is the amount of resources required to maintain an object pool. Objects that hold a lot of resources can be expensive to pool. However, in certain situations, recycling can be extremely efficient, resulting in improved performance and increased scalability. The trade-off is between the cost of holding onto resources while objects are pooled (and inactive) versus the cost of creating and destroying the resources.

It's usually best to enable recycling for objects that cost more to create than they cost to reinitialize. For example, if a component contains a complex structure, and that structure can be reused, it could save a lot of time if the structure didn't have to be recreated every time an instance of the component was activated. This is a case in which you might want to enable recycling, which you would do by returning true from the CanBePooled method.

You could still create the structure in the object's constructor because the constructor is only called once, when a new object is created by the class factory. When recycling is enabled, that only happens when the object pool is empty. The Activate method, on the other hand, is called whether a new instance is created by the class factory or a recycled instance is drawn from the pool. Similarly, the Deactivate method is called every time the object is deactivated, whether it's being destroyed or returned to the pool for recycling.

So, in this example, you'd use the object's Activate method to initialize, or reinitialize, the structure that's being reused, and you'd use the Deactivate method to restore the object to a state that the Activate method can handle. (The Activate method must be able to handle both new objects created by the class factory and reused objects drawn from the pool.) This combined use of the Activate, Deactivate, and CanBePooled methods eliminates the need to recreate reusable resources every time an instance is activated.

For some objects, recycling isn't efficient. For example, if an object acquires a lot of state during its lifetime that isn't reusable, and has little to do during its construction, it's usually cheaper to create a new instance whenever one is needed. In that case, you would return false from the CanBePooled method.

Note   Returning true from the CanBePooled method doesn't guarantee that objects will be recycled; it only gives the MTS run-time environment permission to recycle them. On systems that don't support object pooling, a return value of true is ignored. Returning false from the CanBePooled method guarantees that instances of a component aren't recycled.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl.CanBePooled Method Example (Visual J++)
IObjectControl.CanBePooled Method Example

import com.ms.mtx.*;

boolean CanBePooled()

{

// This object should not be recycled,

// so return false.

return false;

}


IObjectControl.Deactivate Method (Visual J++)
IObjectControl.Deactivate Method

Implementing this method allows an MTS object to perform any cleanup required before it's recycled or destroyed. This method is called by the MTS run-time environment whenever an object is deactivated.

Provided By

IObjectContext

void Deactivate ( );.

Remarks

The MTS run-time environment calls the Deactivate method whenever an object that supports the IObjectControl interface is deactivated. An object is deactivated when it returns from a method in which it called SetComplete or SetAbort, when the transaction in which it executed is committed or aborted, or when the last client to hold a reference on it releases its reference.

If the component supports recycling (returns true from the CanBePooled method), you should use the Deactivate method to reset the object's state to the state in which the Activatemethod expects to find it. You can also use the Deactivate method to release the object's ObjectContext reference or to do other context-specific cleanup. Even if an object supports recycling, it can be beneficial to release certain reusable resources in its Deactivate method. For example, ODBC provides its own connection pooling. It's more efficient to pool a database connection in a general connection pool where it can be used by other objects than it is to keep it tied to a specific object in an object pool.

Example

See Also

Deactivating Objects, Object Pooling and Recycling


IObjectControl.Deactivate Method Example (Visual J++)
IObjectControl.Deactivate Method Example

import com.ms.mtx.*;

void Deactivate( )

{

// Perform any necessary cleanup here.

}


SafeRef Function (Visual Basic)
SafeRef Function

Used by an object to obtain a reference to itself that's safe to pass outside its context.

Syntax

Set safeobject = SafeRef(Me)

Part

safeobject
An object variable representing the current object that's safe to pass to another object or client.

Remarks

When an MTS object wants to pass a self-reference to a client or another object (for example, for use as a callback), it should always call SafeRef first and then pass the reference returned by this call.

To use the SafeRef function, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

Example

See Also

Passing Object References


SafeRef Function Example (Visual Basic)
SafeRef Function Example

Dim anotherObject As New ObjectThatCallsBack

Dim safeMe As My.Class

' Get a safe reference.

Set safeMe = SafeRef(Me)

' Invoke a method on another object, passing the

' safe reference so it can call back.

If Not safeMe Is Nothing Then

Call anotherObject.CallMeBack(safeMe)

Set safeMe = Nothing


GetObjectContext Function (Visual Basic)
GetObjectContext Function

Obtains a reference to the ObjectContext that's associated with the current MTS object.

To use the GetObjectContext function, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

Syntax

Set objectcontext = GetObjectContext ( )

Parameters

objectcontext
An object variable that evaluates to the ObjectContext belonging to the current object.

Remarks

An object should never attempt to pass its ObjectContext reference to another object. If you pass an ObjectContext reference to another object, it will no longer be a valid reference.

When an object obtains a reference to its ObjectContext, it must release the ObjectContext object when it's finished with it.

Example

See Also

Building Scalable Components, Context Objects, CreateInstance Method


GetObjectContext Function, CreateInstance Method Example (Visual Basic)
GetObjectContext Function, CreateInstance Method Example

Dim ctxObject As ObjectContext

Dim objAccount As Bank.Account

' Get the object's ObjectContext.

Set ctxObject = GetObjectContext()

' Use it to instantiate another object.

Set objAccount = _

ctxObject.CreateInstance("Bank.Account")


ObjectContext Object (Visual Basic)
ObjectContext Object

The ObjectContext object provides access to the current object's context.

Remarks

To use the ObjectContext object, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

You obtain a reference to the ObjectContext object by calling the GetObjectContext function. As with any COM object, you must release an ObjectContext object when you're finished using it, unless it's a local variable.

You can use an object's ObjectContext to:

•	Declare that the object's work is complete.

•	Prevent a transaction from being committed, either temporarily or permanently.

•	Instantiate other MTS objects and include their work within the scope of the current object's transaction.

•	Find out if a caller is in a particular role.

•	Find out if security is enabled.

•	Find out if the object is executing within a transaction.

•	Retrieve Microsoft Internet Information Server (IIS) built-in objects.

The ObjectContext object provides the following methods.

Method	Description
Count	Returns the number of context object properties.
CreateInstance	Instantiates another MTS object.
DisableCommit	Declares that the object hasn't finished its work and that its transactional updates are in an inconsistent state. The object retains its state across method calls, and any attempts to commit the transaction before the object calls EnableCommit or SetComplete will result in the transaction being aborted.
EnableCommit	Declares that the object's work isn't necessarily finished, but its transactional updates are in a consistent state. This method allows the transaction to be committed, but the object retains its state across method calls until it calls SetComplete or SetAbort, or until the transaction is completed.
IsCallerInRole	Indicates whether the object's direct caller is in a specified role (either directly or as part of a group).
IsInTransaction	Indicates whether the object is executing within a transaction.
IsSecurityEnabled	Indicates whether security is enabled. MTS security is enabled unless the object is running in the client's process.
Item	Returns a context object property.
Security	Returns a reference to an object's SecurityProperty object.
SetAbort	Declares that the object has completed its work and can be deactivated on returning from the currently executing method, but that its transactional updates are in an inconsistent state or that an unrecoverable error occurred. This means that the transaction in which the object was executing must be aborted. If any object executing within a transaction returns to its client after calling SetAbort, the entire transaction is doomed to abort.
SetComplete	Declares that the object has completed its work and can be deactivated on returning from the currently executing method. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed. When an object that is the root of a transaction calls SetComplete, MTS attempts to commit the transaction on return from the current method.
Note   When an object calls DisableCommit, EnableCommit, SetComplete, or SetAbort from within a method, two flags (Done and Consistent) are set in its ObjectContext. (See the following table for an explanation.) These flags aren't evaluated by the MTS run-time environment until the object's currently executing method returns to its caller. This means that an object can call these methods any number of times from within one of its own methods, but the last call before the object returns to its client is the one that will be in effect.

Method	Done	Consistent
SetAbort	TRUE	FALSE
SetComplete	TRUE	TRUE
DisableCommit	FALSE	FALSE
EnableCommit	FALSE	TRUE
The Done flag, which allows an object to be deactivated and its transaction to commit or abort, is only evaluated after the object returns from the call that first entered its context. For example, suppose client A calls into object B. Object B calls SetComplete and then calls into object C (passing it a safe reference for a callback). Object C calls back to object B, and then object B returns to client A. Object B won't be deactivated when it returns to object C; it will be deactivated when it returns to client A.

See Also

Basic Security Methods, Passing Object References, Context Objects, Transactions, Deactivating Objects


Count Method (Visual Basic)
Count Method

Returns the number of context object properties.

Applies To

ObjectContext Object

Syntax

objectcontext.Count

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Return Value

The number of properties.

Example


CreateInstance Method, ObjectContext (Visual Basic)
CreateInstance Method

Instantiates an MTS object.

Applies To

ObjectContext Object

Syntax

Set object = objectcontext.CreateInstance("progID")

Part

object
An object variable that evaluates to an MTS object.

objectcontext
An object variable that represents the ObjectContext from which to instantiate the new object.

progID
A string expression that is the programmatic ID of the new object's component.

Remarks

CreateInstance creates a COM object. However, the object will have context only if its component is registered with MTS.

When you create an object by using CreateInstance, the new object's context is derived from the current object's ObjectContext and the declarative properties of the new object's component. The new object always executes within the same activity as the object that created it. If the current object has a transaction, the transaction attribute of the new object's component determines whether or not the new object will execute within the scope of that transaction.

If the component's transaction attribute is set to either Requires a transaction or Supports transactions, the new object inherits its creator's transaction. If the component's transaction attribute is set to Requires a new transaction, MTS initiates a new transaction for the new object. If the component's transaction attribute is set to Does not support transactions, the new object doesn't execute under any transaction.

Example

See Also

Creating MTS Objects, Transaction Attributes, MTS Component Requirements


DisableCommit Method (Visual Basic)
DisableCommit Method

Declares that the object's transactional updates are inconsistent and can't be committed in their present state.

Applies To

ObjectContext Object

Syntax

objectcontext.DisableCommit

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

An object that invokes DisableCommit is stateful.

You can use the DisableCommit method to prevent a transaction from committing prematurely between method calls in a stateful object. When an object invokes DisableCommit, it indicates that its work is inconsistent and that it can't complete its work until it receives further method invocations from the client. It also indicates that it needs to maintain its state to perform that work. This prevents the MTS run-time environment from deactivating the object and reclaiming its resources on return from a method call. Once an object has called DisableCommit, if a client attempts to commit the transaction before the object has called EnableCommit or SetComplete, the transaction will abort.

For example, suppose you have a General Ledger component that updates a database. A client makes multiple calls to a General Ledger object to post entries to various accounts. There's an integrity constraint that says the debits must equal the credits when the final method invocation returns, or the transaction must abort. The General Ledger object has an initialization method in which the client informs it of the sequence of calls the client is going to make, and the General Ledger object calls DisableCommit. The object maintains its state between calls so that after the final call in the sequence is made the object can make sure the integrity constraint is satisfied before allowing its work to be committed.

Example

See Also

Transactions


DisableCommit Method Example (Visual Basic)
DisableCommit Method Example

Dim objContext As ObjectContext

Set objContext = GetObjectContext()

objContext.DisableCommit


EnableCommit Method (Visual Basic)
EnableCommit Method

Declares that the current object's work is not necessarily finished, but that its transactional updates are consistent and could be committed in their present form.

Applies To

ObjectContext Object

Syntax

objectcontext.EnableCommit

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

When an object calls EnableCommit, it allows the transaction in which it's participating to be committed, but it maintains its internal state across calls from its clients until it calls SetComplete or SetAbort or until the transaction completes.

EnableCommit is the default state when an object is activated. This is why an object should always call SetComplete or SetAbort before returning from a method, unless you want the object to maintain its internal state for the next call from a client.

Example

See Also

Transactions


EnableCommit Method Example (Visual Basic)
EnableCommit Method Example

Dim objContext As ObjectContext

Set objContext = GetObjectContext()

objContext.EnableCommit


IsCallerInRole Method (Visual Basic)
IsCallerInRole Method

Indicates whether an object's direct caller is in a specified role (either individually or as part of a group).

Applies To

ObjectContext Object

Syntax

objectcontext.IsCallerInRole(role)

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Parameters

objectcontext
An object variable that represents the ObjectContext belonging to the current object.

role
A string expression that contains the name of the role in which to determine if the caller is acting.

Return Values

True
Either the caller is in the specified role, or security is not enabled.

False
The caller is not in the specified role.

Remarks

You use this method to determine whether the direct caller of the currently executing method is associated with a specific role. A role is a symbolic name that represents a user or group of users who have specific access permissions to all components in a given package. Developers define roles when they create a component, and roles are mapped to individual users or groups at deployment time.

IsCallerInRole only applies to the direct caller of the currently executing method. (The direct caller is the process calling into the current server process. It can be either a base client process or a server process.) IsCallerInRole doesn't apply to the process that initiated the call sequence from which the current method was called, or to any other callers in that sequence.

Because IsCallerInRole returns True when the object that invokes it is executing in a client's process, it's a good idea to call IsSecurityEnabled before calling IsCallerInRole. If security isn't enabled, IsCallerInRole won't return an accurate result.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components


IsCallerInRole, IsSecurityEnabled Methods Example (Visual Basic)
IsCallerInRole, IsSecurityEnabled Methods Example

Dim objContext As ObjectContext

Set objContext = GetObjectContext()

If Not objContext Is Nothing Then

' Find out if Security is enabled.

If objContext.IsSecurityEnabled Then

' Find out if the caller is in the right role.

If Not objContext.IsCallerInRole("Manager") Then

' If not, do something appropriate here.

Else

' If so, execute the call normally.

End If

Else

' If security's not enabled, do something

' appropriate here.

End If

End If


IsInTransaction Method (Visual Basic)
IsInTransaction Method

Indicates whether the current object is executing in a transaction.

Applies To

ObjectContext Object

Syntax

objectcontext.IsInTransaction

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Return Values

True
The current object is executing within a transaction.

False
The current object is not executing within a transaction.

Remarks

You can use this method to make sure that an object that requires a transaction never runs without one. For example, if a component that requires a transaction is improperly configured in the MTS Explorer, you can use this method to determine that the object doesn't have a transaction. Then you can return an error to alert the user to the problem, or take whatever action is appropriate.

Example

See Also

Transaction Attributes, Transactions


IsInTransaction Method Example (Visual Basic)
IsInTransaction Method Example

Dim objContext As ObjectContext

Set objContext = GetObjectContext()

If Not objContext Is Nothing Then

' Find out if the object is in a transaction.

If Not objContext.IsInTransaction Then

' If not, do something appropriate here.

End If

End If


IsSecurityEnabled Method (Visual Basic)
IsSecurityEnabled Method

Indicates whether or not security is enabled for the current object. MTS security is enabled unless the object is running in the client's process.

Applies To

ObjectContext Object

Syntax

objectcontext.IsSecurityEnabled

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Return Values

True
Security is enabled for this object.

False
Security is not enabled for this object.

Remarks

MTS security is enabled only if an object is running in a server process. This could be either because the object's component was configured to run in a client's process, or because the component and the client are in the same package. If the object is running in the client's process, there is no security checking and IsSecurityEnabled will always return False.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components


Item Method (Visual Basic)
Item Method

Returns a context object property.

Applies To

ObjectContext Object

Syntax

objectcontext.Item(name)

Part

objectcontext
An object variable that evaluates to the ObjectContext associated with the current object.

name
The name of the context object property to be retrieved.

Return Value

The requested context object property.

Remarks

You can use Item to retrieve the following Microsoft Internet Information Server (IIS) built-in objects:

•	Request

•	Response

•	Server

•	Application

•	Session

For more information, see the IIS documentation.

The Item method is the default method for a collection. Therefore, the following lines of code are equivalent:

oc("Response").Write "<p>" & prop & "</p>"

oc.Item("Response").Write "<p>" & prop & "</p>"

Example


Count, Item Methods Example (Visual Basic)
Count, Item Methods Example

' Get the context object

Dim oc As ObjectContext

Dim str As String

Set oc = GetObjectContext()

' Get the Response object

' Print number of properties

oc("Response").Write "<p>Number of properties: " & oc.Count & "</p>"

' Iterate over properties collection and print the

' names of the properties

For Each prop In oc

    oc("Response").Write "<p>" & prop & "</p>"

Next


Security Property (Visual Basic)
Security Property

Returns a reference to an object's SecurityProperty object.

Applies To

ObjectContext Object

Syntax

Set objectsecurity = objectcontext.Security

Part

objectcontext
An object variable that evaluates to the ObjectContext associated with the current object.

objectsecurity
An object variable that evaluates to the SecurityProperty object associated with the current object.

Example

See Also

Programmatic Security, Advanced Security Methods


Security Property Example (Visual Basic)
Security Property Example

Public Function UsingSecurityMethod() As String

    Dim objCtx As ObjectContext

    Dim objSP As SecurityProperty

    Set objCtx = GetObjectContext()

    Set objSP = objCtx.Security

    UsingSecurityMethod = _

        objSP.GetOriginalCreatorName()

End Function


SetAbort Method (Visual Basic)
SetAbort Method

Declares that the transaction in which the object is executing must be aborted, and that the object should be deactivated on returning from the currently executing method call.

Applies To

ObjectContext Object

Syntax

objectcontext.SetAbort

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

The object is deactivated automatically on return from the method in which it called SetAbort. If the object is the root of an automatic transaction, MTS aborts the transaction. If the object is transactional, but not the root of an automatic transaction, the transaction in which it's participating is doomed to abort. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

You can call SetAbort in error handlers to ensure that a transaction aborts when an error occurs. You can also call SetAbort at the beginning of a method to protect your object from committing prematurely in the event of an unexpected return and then call SetComplete just before the method returns, if all goes well.

Example

See Also

Transactions, Context Objects, Deactivating Objects


SetAbort, SetComplete Methods Example (Visual Basic)
SetAbort, SetComplete Methods Example

Dim ctxObject As ObjectContext

Set ctxObject = GetObjectContext()

On Error GoTo ErrorHandler

' Do some work here. If the work was successful,

' call SetComplete.

ctxObject.SetComplete

Set ctxObject = Nothing

Perform = 0

Exit Function

' If an error occurred, call SetAbort in the error

' handler.

ErrorHandler:

ctxObject.SetAbort

Set ctxObject = Nothing

Perform = -1

Exit Function


SetComplete Method (Visual Basic)
SetComplete Method

Declares that the current object has completed its work and should be deactivated when the currently executing method returns to the client. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed.

Applies To

ObjectContext Object

Syntax

objectcontext.SetComplete

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

The object is deactivated automatically on return from the method in which it called SetComplete. If the object is the root of an automatic transaction, MTS attempts to commit the transaction. However, if any object that was participating in the transaction has called SetAbort, or has called DisableCommit and has not subsequently called EnableCommit or SetComplete, the transaction will be aborted. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

If an object doesn't need to maintain its state after it returns from a method call, it should call SetComplete so that it can be automatically deactivated as soon as it returns and its resources can be reclaimed.

Example

See Also

Transactions, Context Objects, Deactivating Objects


SafeRef Function (Visual C++)
SafeRef Function

Used by an object to obtain a reference to itself that's safe to pass outside its context.

The header file for the SafeRef function is mtx.h.

void* SafeRef (

REFIID riid

UNKNOWN* pUnk

);

Parameter

riid
[in] A reference to the interface ID of the interface that the current object wants to pass to another object or client.

pUnk
[in] A reference to an interface on the current object.

Return Values

Non-NULL
A pointer to the interface specified in the riid parameter that's safe to pass outside the current object's context.

NULL
The object is requesting a safe reference on an object other than itself, or the interface requested in the riid parameter is not implemented.

Remarks

When an MTS object wants to pass a self-reference to a client or another object (for example, for use as a callback), it should always call SafeRef first and then pass the reference returned by this call. An object should never pass a  this pointer, or a self-reference obtained through an internal call to QueryInterface, to a client or to any other object. Once such a reference is passed outside the object's context, it's no longer a valid reference.

Calling SafeRef on a reference that is already safe returns the safe reference unchanged, except that the reference count on the interface is incremented.

When a client calls QueryInterface on a reference that's safe, MTS automatically ensures that the reference returned to the client is also a safe reference.

An object that obtains a safe reference must release the safe reference when it's finished with it.

Note   Safe references have different pointer values than their unsafe counterparts. For example, this and the safe version of this do not have the same value. It's important to be aware of this when testing whether two pointers refer to the same object. Calling QueryInterface for IID_IUnknown on each of the pointers and comparing the value of the returned pointers may result in the wrong conclusion. It's possible that both pointers refer to the same object, but that one is a safe reference and the other isn't. If both references are safe references, they can be compared in the usual way. This is only a consideration for MTS objects, because clients should never have access to unsafe references.

Example

See Also

Passing Object References


SafeRef Function Example (Visual C++)
SafeRef Function Example

#include <mtx.h>

IMyInterface* pSafeMyObject = NULL;

IAnotherObject* pOtherObject = NULL;

HRESULT hr;

// Get a safe reference.

pSafeMyObject = SafeRef(IID_IMyInterface,

(IUnknown*)this);

// Invoke a method on another object, passing the

// safe reference so it can call back.

hr = pOtherObject->CallMeBack(pSafeMyObject);

// Release the safe reference.

safeMyObject->Release();


GetObjectContext Function (Visual C++)
GetObjectContext Function

Obtains a reference to the IObjectContext interface on the ObjectContext that's associated with the current MTS object.

The header file for the GetObjectContext function is mtx.h.

HRESULT GetObjectContext (

IObjectContext** ppInstanceContext

);

Parameters

ppInstanceContext
[out] A reference to the IObjectContext interface on the object's context. If the object's component hasn't been imported into an MTS package, or if GetObjectContext is called from a constructor or an IUnknown method, this will be set to a NULL pointer.

Return Values

S_OK
A reference to the IObjectContext interface on the current object's context is returned in the ppInstanceContext parameter.

E_INVALIDARG
The argument passed in the ppInstanceContext parameter is invalid.

E_UNEXPECTED
An unexpected error occurred.

CONTEXT_E_NOCONTEXT
The current object doesn't have a context associated with it, because either the component wasn't imported into a package or the object wasn't created with one of the MTS CreateInstance methods. This error will also be returned if the GetObjectContext method was called from the constructor or from an IUnknown method.

Remarks

An object's context is not accessible from an object's constructor or from any IUnknown method (QueryInterface, AddRef, or Release).

An object should never attempt to pass its ObjectContext reference to another object. If you pass an ObjectContext reference to another object, it will no longer be a valid reference.

When an object obtains a reference to its ObjectContext, it must release the ObjectContext object when it's finished with it.

Example

See Also

Building Scalable Components, Context Objects, IObjectContext::CreateInstance Method


GetObjectContext Function, IObjectContext::CreateInstance Method Example (Visual C++)
GetObjectContext Function, IObjectContext::CreateInstance Method Example

#include <mtx.h>

IObjectContext* pObjectContext = NULL;

IAccount* pAccount = NULL;

HRESULT hr;

// Get the object's ObjectContext.

hr = GetObjectContext(&pObjectContext);

// Use it to instantiate another object.

hr = pObjectContext->CreateInstance(CLSID_CAccount,

IID_IAccount, (void**)&pAccount);


IObjectContext Interface (Visual C++)
IObjectContext Interface

The IObjectContext interface provides access to the current object's context.

Remarks

The header file for the IObjectContext interface is mtx.h.

You obtain a reference to the IObjectContext interface by calling the GetObjectContext function. As with any COM object, you must release an ObjectContext object when you're finished using it.

You can use an object's ObjectContext to:

•	Declare that the object's work is complete.

•	Prevent a transaction from being committed, either temporarily or permanently.

•	Instantiate other MTS objects and include their work within the scope of the current object's transaction.

•	Find out if a caller is in a particular role.

•	Find out if security is enabled.

•	Find out if the object is executing within a transaction.

The IObjectContext interface exposes the following methods.

Method	Description
CreateInstance	Instantiates another MTS object.
DisableCommit	Declares that the object hasn't finished its work and that its transactional updates are in an inconsistent state. The object retains its state across method calls, and any attempts to commit the transaction before the object calls EnableCommit or SetComplete will result in the transaction being aborted.
EnableCommit	Declares that the object's work isn't necessarily finished, but its transactional updates are in a consistent state. This method allows the transaction to be committed, but the object retains its state across method calls until it calls SetComplete or SetAbort, or until the transaction is completed.
IsCallerInRole	Indicates whether the object's direct caller is in a specified role (either directly or as part of a group).
IsInTransaction	Indicates whether the object is executing within a transaction.
IsSecurityEnabled	Indicates whether security is enabled. MTS security is enabled unless the object is running in the client's process.
SetAbort	Declares that the object has completed its work and can be deactivated on returning from the currently executing method, but that its transactional updates are in an inconsistent state or that an unrecoverable error occurred. This means that the transaction in which the object was executing must be aborted. If any object executing within a transaction returns to its client after calling SetAbort, the entire transaction is doomed to abort.
SetComplete	Declares that the object has completed its work and can be deactivated on returning from the currently executing method. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed. When an object that is the root of a transaction calls SetComplete, MTS attempts to commit the transaction on return from the current method.
Note   When an object calls DisableCommit, EnableCommit, SetComplete, or SetAbort from within a method, two flags (Done and Consistent) are set in its ObjectContext. (See the following table for an explanation.) These flags aren't evaluated by the MTS run-time environment until the object's currently executing method returns to its caller. This means that an object can call these methods any number of times from within one of its own methods, but the last call before the object returns to its client is the one that will be in effect.

Method	Done	Consistent
SetAbort	TRUE	FALSE
SetComplete	TRUE	TRUE
DisableCommit	FALSE	FALSE
EnableCommit	FALSE	TRUE
The Done flag, which allows an object to be deactivated and its transaction to commit or abort, is only evaluated after the object returns from the call that first entered its context. For example, suppose client A calls into object B. Object B calls SetComplete and then calls into object C (passing it a safe reference for a callback). Object C calls back to object B, and then object B returns to client A. Object B won't be deactivated when it returns to object C; it will be deactivated when it returns to client A.

See Also

Basic Security Methods, Passing Object References, Context Objects, Transactions, Deactivating Objects


IObjectContext::CreateInstance Method (Visual C++)
IObjectContext::CreateInstance Method

Instantiates an MTS object.

Provided By

IObjectContext

HRESULT IObjectContext::CreateInstance (

REFCLSID rclsid,

REFIID riid,

LPVOID FAR* ppvObj

);

Parameter

rclsid
[in] A reference to the CLSID of the type of object to instantiate.

riid
[in] A reference to the interface ID of the interface through which you want to communicate with the new object.

ppvObj
[out] A reference to the requested interface on the new object.

Return Values

S_OK
The object was created and a reference to it is returned in the ppvObj parameter.

REGDB_E_CLASSNOTREG
The component specified by rclsid is not registered as a COM component.

E_OUTOFMEMORY
There's not enough memory available to instantiate the object.

E_INVALIDARG
The argument passed in the ppvObj parameter is invalid.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object, and the other object calls CreateInstance using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

CreateInstance creates a COM object. However, the object will have context only if its component is registered with MTS.

When you create an object by using CreateInstance, the new object's context is derived from the current object's ObjectContext and the declarative properties of the new object's component. The new object always executes within the same activity as the object that created it. If the current object has a transaction, the transaction attribute of the new object's component determines whether or not the new object will execute within the scope of that transaction.

If the component's transaction attribute is set to either Requires a transaction or Supports transactions, the new object inherits its creator's transaction. If the component's transaction attribute is set to Requires a new transaction, MTS initiates a new transaction for the new object. If the component's transaction attribute is set to Does not support transactions, the new object doesn't execute under any transaction.

If the Microsoft Distributed Transaction Coordinator is not running and the object is transactional, the object is successfully created. However, method calls to that object will fail with CONTEXT_E_TMNOTAVAILABLE. Objects cannot recover from this condition and should be released.

MTS always uses standard marshaling. Even if a component exposes the IMarshal interface, its IMarshal methods will never be called by the MTS run-time environment.

You can't create MTS objects as part of an aggregation. In this respect, using CreateInstance is like using CoCreateInstance and specifying NULL for the controlling IUnknown interface (pUnkOuter).

Example

See Also

Creating MTS Objects, Transaction Attributes, MTS Component Requirements


IObjectContext::DisableCommit Method (Visual C++)
IObjectContext::DisableCommit Method

Declares that the object's transactional updates are inconsistent and can't be committed in their present state.

Provided By

IObjectContext

HRESULT IObjectContext::DisableCommit ( );

Return Values

S_OK
The call to DisableCommit succeeded. The object's transactional updates can't be committed until the object calls either EnableCommit or SetComplete.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object and the other object calls DisableCommit using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

CONTEXT_E_NOCONTEXT
The current object doesn't have a context associated with it. This is probably because it wasn't created with one of the MTS CreateInstance methods.

Remarks

An object that invokes DisableCommit is stateful.

You can use the DisableCommit method to prevent a transaction from committing prematurely between method calls in a stateful object. When an object invokes DisableCommit, it indicates that its work is inconsistent and that it can't complete its work until it receives further method invocations from the client. It also indicates that it needs to maintain its state to perform that work. This prevents the MTS run-time environment from deactivating the object and reclaiming its resources on return from a method call. Once an object has called DisableCommit, if a client attempts to commit the transaction before the object has called EnableCommit or SetComplete, the transaction will abort.

For example, suppose you have a General Ledger component that updates a database. A client makes multiple calls to a General Ledger object to post entries to various accounts. There's an integrity constraint that says the debits must equal the credits when the final method invocation returns, or the transaction must abort. The General Ledger object has an initialization method in which the client informs it of the sequence of calls the client is going to make, and the General Ledger object calls DisableCommit. The object maintains its state between calls so that after the final call in the sequence is made the object can make sure the integrity constraint is satisfied before allowing its work to be committed.

Example

See Also

Transactions


IObjectContext::DisableCommit Method Example (Visual C++)
IObjectContext::DisableCommit Method Example

#include <mtx.h>

IObjectContext* pObjectContext = NULL;

HRESULT hr;

hr = GetObjectContext(&pObjectContext);

hr = pObjectContext->DisableCommit();


IObjectContext::EnableCommit Method (Visual C++)
IObjectContext::EnableCommit Method

Declares that the current object's work is not necessarily finished, but that its transactional updates are consistent and could be committed in their present form.

Provided By

IObjectContext

HRESULT IObjectContext::EnableCommit ( );

Return Values

S_OK
The call to EnableCommit succeeded and the object's transactional updates can now be committed.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object and the other object calls EnableCommit using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

When an object calls EnableCommit, it allows the transaction in which it's participating to be committed, but it maintains its internal state across calls from its clients until it calls SetComplete or SetAbort or until the transaction completes.

EnableCommit is the default state when an object is activated. This is why an object should always call SetComplete or SetAbort before returning from a method, unless you want the object to maintain its internal state for the next call from a client.

Example

See Also

Transactions


IObjectContext::EnableCommit Method Example (Visual C++)
IObjectContext::EnableCommit Method Example

#include <mtx.h>

IObjectContext* pObjectContext = NULL;

HRESULT hr;

hr = GetObjectContext(&pObjectContext);

hr = pObjectContext->EnableCommit();


IObjectContext::IsCallerInRole Method (Visual C++)
IObjectContext::IsCallerInRole Method

Indicates whether an object's direct caller is in a specified role (either individually or as part of a group).

Provided By

IObjectContext

HRESULT IObjectContext::IsCallerInRole (

BSTR bstrRole,

BOOL* pfIsInRole

);

Parameters

bstrRole
[in] The name of the role in which you want to determine whether the caller is acting.

pfIsInRole
[out] TRUE if the caller is in the specified role, FALSE if not. This parameter will also be set to TRUE if security is not enabled.

Return Values

S_OK
The role specified in the bstrRole parameter is a recognized role, and the Boolean result returned in the pfIsInRole parameter indicates whether or not the caller is in that role.

CONTEXT_E_
ROLENOTFOUND
The role specified in the bstrRole parameter does not exist.

E_INVALIDARG
One or more of the arguments passed in is invalid.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object and the other object calls IsCallerInRole using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

You use this method to determine whether the direct caller of the currently executing method is associated with a specific role. A role is a symbolic name that represents a user or group of users who have specific access permissions to all components in a given package. Developers define roles when they create a component, and roles are mapped to individual users or groups at deployment time.

IsCallerInRole only applies to the direct caller of the currently executing method. (The direct caller is the process calling into the current server process. It can be either a base client process or a server process.) IsCallerInRole doesn't apply to the process that initiated the call sequence from which the current method was called, or to any other callers in that sequence.

Because IsCallerInRole returns TRUE when the object that invokes it is executing in a client's process, it's a good idea to call IsSecurityEnabled before calling IsCallerInRole. If security isn't enabled, IsCallerInRole won't return an accurate result.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components


IObjectContext::IsCallerInRole, IObjectContext::IsSecurityEnabled Methods Example (Visual C++)
IObjectContext::IsCallerInRole, IObjectContext::IsSecurityEnabled Methods Example

#include <mtx.h>

IObjectContext* pObjectContext = NULL;

BSTR stRole = SysAllocString(L"Manager");

VARIANT_BOOL fIsInRole;

HRESULT hr;

hr = GetObjectContext(&pObjectContext);

// Find out if security is enabled.

if (pObjectContext->IsSecurityEnabled()) {

//Then find out if the caller is in the right role.

fIsInRole = pObjectContext->IsCallerInRole

(stRole, &fIsInRole)

SysFreeString(stRole);

if (!fIsInRole) {

// If not, do something appropriate here.

}

}

else {

// If security's not enabled, do something

// appropriate here.

}


IObjectContext::IsInTransaction Method (Visual C++)
IObjectContext::IsInTransaction Method

Indicates whether the current object is executing in a transaction.

Provided By

IObjectContext

BOOL IObjectContext::IsInTransaction ( );

Return Values

TRUE
The current object is executing within a transaction.

FALSE
The current object is not executing within a transaction.

Remarks

You can use this method to make sure that an object that requires a transaction never runs without one. For example, if a component that requires a transaction is improperly configured in the MTS Explorer, you can use this method to determine that the object doesn't have a transaction. Then you can return an error to alert the user to the problem, or take whatever action is appropriate.

Example

See Also

Transaction Attributes, Transactions


IObjectContext::IsInTransaction Method Example (Visual C++)
IObjectContext::IsInTransaction Method Example

#include <mtx.h>

IObjectContext* pObjectContext = NULL;

VARIANT_BOOL fInTransaction;

HRESULT hr;

hr = GetObjectContext(&pObjectContext);

// Find out if the object is in a transaction.

fInTransaction = pObjectContext->IsInTransaction();

if (!fInTransaction) {

// If not, do something appropriate here.

}


IObjectContext::IsSecurityEnabled Method (Visual C++)
IObjectContext::IsSecurityEnabled Method

Indicates whether or not security is enabled for the current object. MTS security is enabled unless the object is running in the client's process.

Provided By

IObjectContext

BOOL IObjectContext::IsSecurityEnabled ( );

Return Values

TRUE
Security is enabled for this object.

FALSE
Security is not enabled for this object.

Remarks

MTS security is enabled only if an object is running in a server process. This could be either because the object's component was configured to run in a client's process, or because the component and the client are in the same package. If the object is running in the client's process, there is no security checking and IsSecurityEnabled will always return FALSE.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components


IObjectContext::SetAbort Method (Visual C++)
IObjectContext::SetAbort Method

Declares that the transaction in which the object is executing must be aborted, and that the object should be deactivated on returning from the currently executing method call.

Provided By

IObjectContext

HRESULT IObjectContext::SetAbort ( );

Return Values

S_OK
The call to SetAbort succeeded and the transaction will be aborted.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object and the other object calls SetAbort using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

The object is deactivated automatically on return from the method in which it called SetAbort. If the object is the root of an automatic transaction, MTS aborts the transaction. If the object is transactional, but not the root of an automatic transaction, the transaction in which it's participating is doomed to abort. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

You can call SetAbort in error handlers to ensure that a transaction aborts when an error occurs. You can also call SetAbort at the beginning of a method to protect your object from committing prematurely in the event of an unexpected return and then call SetComplete just before the method returns, if all goes well.

Example

See Also

Transactions, Context Objects, Deactivating Objects


IObjectContext::SetAbort, IObjectContext::SetComplete Methods Example (Visual C++)
IObjectContext::SetAbort, IObjectContext::SetComplete Methods Example

#include <mtx.h>

IObjectContext* pObjectContext = NULL;

HRESULT hr;

hr = GetObjectContext(&pObjectContext);

// Do some work here.

// If the work was successful, call SetComplete.

if (SUCCEEDED(hr)) {

if (pObjectContext)

pObjectContext->SetComplete();

}

// Otherwise, call SetAbort.

else {

if (pObjectContext)

pObjectContext->SetAbort();

}


IObjectContext::SetComplete Method (Visual C++)
IObjectContext::SetComplete Method

Declares that the current object has completed its work and should be deactivated when the currently executing method returns to the client. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed.

Provided By

IObjectContext

HRESULT IObjectContext::SetComplete ( );

Return Values

S_OK
The call to SetComplete succeeded.

E_UNEXPECTED
An unexpected error occurred. This can happen if one object passes its IObjectContext pointer to another object and the other object calls SetComplete using this pointer. An IObjectContext pointer is not valid outside the context of the object that originally obtained it.

Remarks

The object is deactivated automatically on return from the method in which it called SetComplete. If the object is the root of an automatic transaction, MTS attempts to commit the transaction. However, if any object that was participating in the transaction has called SetAbort, or has called DisableCommit and has not subsequently called EnableCommit or SetComplete, the transaction will be aborted. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

If an object doesn't need to maintain its state after it returns from a method call, it should call SetComplete so that it can be automatically deactivated as soon as it returns and its resources can be reclaimed.

Example

See Also

Transactions, Context Objects, Deactivating Objects


MTx.SafeRef Method (Visual J++)
MTx.SafeRef Method

Used by an object to obtain a reference to itself that's safe to pass outside its context.

SafeRef is a static method of the MTx class, which is declared in the package com.ms.mtx.

Note  The class MTx has only static methods and has no public constructor. You can't create an instance of this class.

New applications should call getSafeRef.

IUnknown SafeRef (

IUnknown obj

);

Parameter

obj
[in] A reference to an interface on the current object.

Return Value

A reference to the IUnknown interface on the current object that's safe to pass outside the current object's context.

Remarks

When an MTS object wants to pass a self-reference to a client or another object (for example, for use as a callback), it should always call SafeRef first and then pass the reference returned by this call. An object should never pass a reference to this to a client or to any other object. Once such a reference is passed outside the object's context, it's no longer a valid reference.

Regardless of the interface ID you pass to SafeRef, it always returns the IUnknown interface on the object that calls it. You should immediately cast the returned value to the interface that you want to pass outside the object.

Calling SafeRef on a reference that is already safe returns the safe reference unchanged, except that the reference count on the interface is incremented.

Example

See Also

Passing Object References


MTx.SafeRef Method Example (Visual J++)
MTx.SafeRef Method Example

import com.ms.mtx.*;

IMyInterface safeMyObject = null;

IAnotherObject someOtherObject = null;

// Get a safe reference.

safeMyObject = (IMyInterface) MTx.SafeRef(this);

// Invoke a method on another object, passing the

// safe reference so it can call back.

someOtherObject.CallMeBack(safeMyObject);


MTx.GetObjectContext Method (Visual J++)
MTx.GetObjectContext Method

Obtains a reference to the IObjectContext interface on the ObjectContext that's associated with the current MTS object.

GetObjectContext is a static method of the MTx class, which is declared in the package com.ms.mtx.

Note   The MTx class has only static methods and has no public constructor. You can't create an instance of this class.

IObjectContext GetObjectContext ( );

Return Value

A reference to the IObjectContext interface on the current object's context. GetObjectContext will return null if it is called from a constructor or finalizer, or if the object's component hasn't been imported into an MTS package.

Remarks

An object should never attempt to pass its ObjectContext reference to another object. If you pass an ObjectContext reference to another object, it will no longer be a valid reference.

Example

See Also

Building Scalable Components, Context Objects, IObjectContext.CreateInstance Method


MTx.GetObjectContext Method, IObjectContext.CreateInstance Method Example (Visual J++)
MTx.GetObjectContext Method, IObjectContext.CreateInstance Method Example

import com.ms.mtx.*;

IAccount account = null;

// Get the object's ObjectContext and

// use it to instantiate another object.

account = (IAccount) MTx.GetObjectContext().

CreateInstance(CAccount.clsid, IAccount.iid);


IObjectContext Interface (Visual J++)
IObjectContext Interface

The IObjectContext interface provides access to the current object's context.

Remarks

New applications should use the Context class.

The IObjectContext interface is declared in the package com.ms.mtx.

You obtain a reference to the IObjectContext interface by calling the MTx.GetObjectContext method. As with any COM object, you must release an ObjectContext object when you're finished using it.

You can use an object's ObjectContext to:

•	Declare that the object's work is complete.

•	Prevent a transaction from being committed, either temporarily or permanently.

•	Instantiate other MTS objects and include their work within the scope of the current object's transaction.

•	Find out if a caller is in a particular role.

•	Find out if security is enabled.

•	Find out if the object is executing within a transaction.

The IObjectContext interface exposes the following methods.

Method	Description
CreateInstance	Instantiates another MTS object.
DisableCommit	Declares that the object hasn't finished its work and that its transactional updates are in an inconsistent state. The object retains its state across method calls, and any attempts to commit the transaction before the object calls EnableCommit or SetComplete will result in the transaction being aborted.
EnableCommit	Declares that the object's work isn't necessarily finished, but its transactional updates are in a consistent state. This method allows the transaction to be committed, but the object retains its state across method calls until it calls SetComplete or SetAbort, or until the transaction is completed.
IsCallerInRole	Indicates whether the object's direct caller is in a specified role (either directly or as part of a group).
IsInTransaction	Indicates whether the object is executing within a transaction.
IsSecurityEnabled	Indicates whether security is enabled. MTS security is enabled unless the object is running in the client's process.
SetAbort	Declares that the object has completed its work and can be deactivated on returning from the currently executing method, but that its transactional updates are in an inconsistent state or that an unrecoverable error occurred. This means that the transaction in which the object was executing must be aborted. If any object executing within a transaction returns to its client after calling SetAbort, the entire transaction is doomed to abort.
SetComplete	Declares that the object has completed its work and can be deactivated on returning from the currently executing method. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed. When an object that is the root of a transaction calls SetComplete, MTS attempts to commit the transaction on return from the current method.
Note   When an object calls DisableCommit, EnableCommit, SetComplete, or SetAbort from within a method, two flags (Done and Consistent) are set in its ObjectContext. (See the following table for an explanation.) These flags aren't evaluated by the MTS run-time environment until the object's currently executing method returns to its caller. This means that an object can call these methods any number of times from within one of its own methods, but the last call before the object returns to its client is the one that will be in effect.

Method	Done	Consistent
SetAbort	TRUE	FALSE
SetComplete	TRUE	TRUE
DisableCommit	FALSE	FALSE
EnableCommit	FALSE	TRUE
The Done flag, which allows an object to be deactivated and its transaction to commit or abort, is only evaluated after the object returns from the call that first entered its context. For example, suppose client A calls into object B. Object B calls SetComplete and then calls into object C (passing it a safe reference for a callback). Object C calls back to object B, and then object B returns to client A. Object B won't be deactivated when it returns to object C; it will be deactivated when it returns to client A.

See Also

Basic Security Methods, Passing Object References, Context Objects, Transactions, Deactivating Objects


IObjectContext.CreateInstance Method (Visual J++)
IObjectContext.CreateInstance Method

Instantiates an MTS object.

New applications should call createInstance.

Provided By

IObjectContext Interface

IUnknown CreateInstance (

_Guid clsid,

_Guid iid,

);

Parameter

clsid
[in] The clsid of the type of object to instantiate.

iid
[in] Any interface that's implemented by the object you want to instantiate.

Return Value

A reference to the IUnknown interface on the newly created object.

Remarks

CreateInstance creates a COM object. However, the object will have context only if its component is registered with MTS.

When you create an object by using CreateInstance, the new object's context is derived from the current object's ObjectContext and the declarative properties of the new object's component. The new object always executes within the same activity as the object that created it. If the current object has a transaction, the transaction attribute of the new object's component determines whether or not the new object will execute within the scope of that transaction.

If the component's transaction attribute is set to either Requires a transaction or Supports transactions, the new object inherits its creator's transaction. If the component's transaction attribute is set to Requires a new transaction, MTS initiates a new transaction for the new object. If the component's transaction attribute is set to Does not support transactions, the new object doesn't execute under any transaction.

CreateInstance always returns the IUnknown interface on the newly instantiated object. You should immediately cast the returned value to the interface through which you want to communicate with the new object. The interface ID you pass in the iid parameter doesn't have to be the same interface as the one to which you cast the returned value, but it must be an interface that's implemented by the object you're instantiating.

MTS always uses standard marshaling. Even if a component exposes the IMarshal interface, its IMarshal methods will never be called by the MTS run-time environment.

You can't create MTS objects as part of an aggregation.

Example

See Also

Creating MTS Objects, Transaction Attributes, MTS Component Requirements


IObjectContext.DisableCommit Method (Visual J++)
IObjectContext.DisableCommit Method

Declares that the object's transactional updates are inconsistent and can't be committed in their present state.

New applications should call disableCommit.

Provided By

IObjectContext

void DisableCommit ( );

Remarks

An object that invokes DisableCommit is stateful.

You can use the DisableCommit method to prevent a transaction from committing prematurely between method calls in a stateful object. When an object invokes DisableCommit, it indicates that its work is inconsistent and that it can't complete its work until it receives further method invocations from the client. It also indicates that it needs to maintain its state to perform that work. This prevents the MTS run-time environment from deactivating the object and reclaiming its resources on return from a method call. Once an object has called DisableCommit, if a client attempts to commit the transaction before the object has called EnableCommit or SetComplete, the transaction will abort.

For example, suppose you have a General Ledger component that updates a database. A client makes multiple calls to a General Ledger object to post entries to various accounts. There's an integrity constraint that says the debits must equal the credits when the final method invocation returns, or the transaction must abort. The General Ledger object has an initialization method in which the client informs it of the sequence of calls the client is going to make, and the General Ledger object calls DisableCommit. The object maintains its state between calls so that after the final call in the sequence is made the object can make sure the integrity constraint is satisfied before allowing its work to be committed.

Example

See Also

Transactions


IObjectContext.DisableCommit Method Example (Visual J++)
IObjectContext.DisableCommit Method Example

import com.ms.mtx.*;

MTx.GetObjectContext().DisableCommit();


IObjectContext.EnableCommit Method (Visual J++)
IObjectContext.EnableCommit Method

Declares that the current object's work is not necessarily finished, but that its transactional updates are consistent and could be committed in their present form.

New applications should call enableCommit.

Provided By

IObjectContext

void EnableCommit ( );

Remarks

When an object calls EnableCommit, it allows the transaction in which it's participating to be committed, but it maintains its internal state across calls from its clients until it calls SetComplete or SetAbort or until the transaction completes.

EnableCommit is the default state when an object is activated. This is why an object should always call SetComplete or SetAbort before returning from a method, unless you want the object to maintain its internal state for the next call from a client.

Example

See Also

Transactions


IObjectContext.EnableCommit Method Example (Visual J++)
IObjectContext.EnableCommit Method Example

import com.ms.mtx.*;

MTx.GetObjectContext().EnableCommit();

}


IObjectContext.IsCallerInRole Method (Visual J++)
IObjectContext.IsCallerInRole Method

Indicates whether an object's direct caller is in a specified role (either individually or as part of a group).

New applications should call isCallerInRole.

Provided By

IObjectContext

boolean IsCallerInRole (

String bstrRole

);

Parameters

bstrRole
[in] The name of the role in which you want to determine whether the caller is acting.

Return Values

true
Either the caller is in the specified role, or security is not enabled.

false
The caller is not in the specified role.

Remarks

You use this method to determine whether the direct caller of the currently executing method is associated with a specific role. A role is a symbolic name that represents a user or group of users who have specific access permissions to all components in a given package. Developers define roles when they create a component, and roles are mapped to individual users or groups at deployment time.

IsCallerInRole only applies to the direct caller of the currently executing method. (The direct caller is the process calling into the current server process. It can be either a base client process or a server process.) IsCallerInRole doesn't apply to the process that initiated the call sequence from which the current method was called, or to any other callers in that sequence.

Because IsCallerInRole returns true when the object that invokes it is executing in a client's process, it's a good idea to call IsSecurityEnabled before calling IsCallerInRole. If security isn't enabled, IsCallerInRole won't return an accurate result.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components


IObjectContext.IsCallerInRole, IObjectContext.IsSecurityEnabled Methods Example (Visual J++)
IObjectContext.IsCallerInRole, IObjectContext.IsSecurityEnabled Methods Example

import com.ms.mtx.*;

IObjectContext objContext = null;

objContext = MTx.GetObjectContext();

// Find out if Security is enabled.

if (objContext.IsSecurityEnabled()) {

//Then find out if the caller is in the right role.

if (!objContext.IsCallerInRole("Manager")) {

// If not, do something appropriate here.

}

}

else {

// If security's not enabled, do something

// appropriate here.

}


IObjectContext.IsInTransaction Method (Visual J++)
IObjectContext.IsInTransaction Method

Indicates whether the current object is executing in a transaction.

New applications should call isInTransaction.

Provided By

IObjectContext

boolean IsInTransaction ( );

Return Values

true
The current object is executing within a transaction.

false
The current object is not executing within a transaction.

Remarks

You can use this method to make sure that an object that requires a transaction never runs without one. For example, if a component that requires a transaction is improperly configured in the MTS Explorer, you can use this method to determine that the object doesn't have a transaction. Then you can return an error to alert the user to the problem, or take whatever action is appropriate.

Example

See Also

Transaction Attributes, Transactions


IObjectContext.IsInTransaction Method Example (Visual J++)
IObjectContext.IsInTransaction Method Example

import com.ms.mtx.*;

// Find out if the object is in a transaction.

if (!MTx.GetObjectContext().IsInTransaction()) {

// If not, do something appropriate here.

}


IObjectContext.IsSecurityEnabled Method (Visual J++)
IObjectContext.IsSecurityEnabled Method

Indicates whether or not security is enabled for the current object. MTS security is enabled unless the object is running in the client's process.

New applications should call isSecurityEnabled.

Provided By

IObjectContext

boolean IsSecurityEnabled ( );

Return Values

true
Security is enabled for this object.

false
Security is not enabled for this object.

Remarks

MTS security is enabled only if an object is running in a server process. This could be either because the object's component was configured to run in a client's process, or because the component and the client are in the same package. If the object is running in the client's process, there is no security checking and IsSecurityEnabled will always return false.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components


IObjectContext.SetAbort Method (Visual J++)
IObjectContext.SetAbort Method

Declares that the transaction in which the object is executing must be aborted, and that the object should be deactivated on returning from the currently executing method call.

New applications should call setAbort.

Provided By

IObjectContext

void SetAbort ( );

Remarks

The object is deactivated automatically on return from the method in which it called SetAbort. If the object is the root of an automatic transaction, MTS aborts the transaction. If the object is transactional, but not the root of an automatic transaction, the transaction in which it's participating is doomed to abort. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

You can call SetAbort in error handlers to ensure that a transaction aborts when an error occurs. You can also call SetAbort at the beginning of a method to protect your object from committing prematurely in the event of an unexpected return and then call SetComplete just before the method returns, if all goes well.

Example

See Also

Transactions, Context Objects, Deactivating Objects


IObjectContext.SetAbort, IObjectContext.SetComplete Methods Example (Visual J++)
IObjectContext.SetAbort, IObjectContext.SetComplete Methods Example

import com.ms.mtx.*;

boolean success = false;

// Do some work here.

// If the work was successful, call SetComplete

if (success)

MTx.GetObjectContext().SetComplete();

// Otherwise, call SetAbort.

else

MTx.GetObjectContext().SetAbort();


IObjectContext.SetComplete Method (Visual J++)
IObjectContext.SetComplete Method

Declares that the current object has completed its work and should be deactivated when the currently executing method returns to the client. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed.

New applications should call setComplete.

Provided By

IObjectContext

void SetComplete ( );

Remarks

The object is deactivated automatically on return from the method in which it called SetComplete. If the object is the root of an automatic transaction, MTS attempts to commit the transaction. However, if any object that was participating in the transaction has called SetAbort, or has called DisableCommit and has not subsequently called EnableCommit or SetComplete, the transaction will be aborted. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

If an object doesn't need to maintain its state after it returns from a method call, it should call SetComplete so that it can be automatically deactivated as soon as it returns and its resources can be reclaimed.

Example

See Also

Transactions, Context Objects, Deactivating Objects


Context.getSafeRef Method (Visual J++)
getSafeRef Method

Used by an object to obtain a reference to itself that's safe to pass outside its context.

getSafeRef is a static method of the Context class, which is declared in the package com.ms.mtx.

Note  The class Context has only static methods and has no public constructor. You can't create an instance of this class.

Provided By

Context class

IUnknown getSafeRef (

IUnknown unknown

);

Parameter

unknown
[in] A reference to the current object.

Return Value

A reference to the current object that's safe to pass outside the current object's context.

Remarks

When an MTS object wants to pass a self-reference to a client or another object (for example, for use as a callback), it should always call getSafeRef first and then pass the reference returned by this call. An object should never pass a reference to to a client or to any other object. Once such a reference is passed outside the object's context, it's no longer a valid reference.

Calling getSafeRef on a reference that is already safe returns the safe reference unchanged.

See Also

Passing Object References


getObjectContext Method (Visual J++)
getObjectContext Method

Obtains a reference to the ObjectContext that's associated with the current MTS object.

getObjectContext is a static method of the Context class, which is declared in the package com.ms.mtx.

Note  The class Context has only static methods and has no public constructor. You can't create an instance of this class.

Return Value

A reference to the IObjectContext interface on the current object's context. getObjectContext will return null if it is called from a constructor or finalizer, or if the object's component hasn't been imported into an MTS package.

Remarks

An object should never attempt to pass its ObjectContext reference to another object. If you pass an ObjectContext reference to another object, it will no longer be a valid reference.

See Also

Building Scalable Components, Context Objects


Context Class (Visual J++)
Context Class

The Context class provides access to the current object's context.

Remarks

The Context class is in the package com.ms.mtx.

You can use an object's Context to:

•	Declare that the object's work is complete.

•	Prevent a transaction from being committed, either temporarily or permanently.

•	Instantiate other MTS objects and include their work within the scope of the current object's transaction.

•	Find out if a caller is in a particular role.

•	Find out if security is enabled.

•	Find out if the object is executing within a transaction.

The Context class exposes the following methods.

Method	Description
createObject	Instantiates another MTS object.
disableCommit	Declares that the object hasn't finished its work and that its transactional updates are in an inconsistent state. The object retains its state across method calls, and any attempts to commit the transaction before the object calls enableCommit or setComplete will result in the transaction being aborted.
enableCommit	Declares that the object's work isn't necessarily finished, but its transactional updates are in a consistent state. This method allows the transaction to be committed, but the object retains its state across method calls until it calls setComplete or setAbort, or until the transaction is completed.
getProperty	Returns a context object property.
getPropertyNames	Returns the names of the context object properties.
isCallerInRole	Indicates whether the object's direct caller is in a specified role (either directly or as part of a group).
isInTransaction	Indicates whether the object is executing within a transaction.
isSecurityEnabled	Indicates whether security is enabled. MTS security is enabled unless the object is running in the client's process.
getSafeRef	Used by an object to obtain a reference to itself that's safe to pass outside its context.
setAbort	Declares that the object has completed its work and can be deactivated on returning from the currently executing method, but that its transactional updates are in an inconsistent state or that an unrecoverable error occurred. This means that the transaction in which the object was executing must be aborted. If any object executing within a transaction returns to its client after calling setAbort, the entire transaction is doomed to abort.
setComplete	Declares that the object has completed its work and can be deactivated on returning from the currently executing method. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed. When an object that is the root of a transaction calls setComplete, MTS attempts to commit the transaction on return from the current method.
getDirectCallerName	Retrieves the user name associated with the external process that called the currently executing method.
getDirectCreatorName	Retrieves the user name associated with the external process that directly created the current object.
getOriginalCallerName	Retrieves the user name associated with the base process that initiated the call sequence from which the current method was called.
getOriginalCreatorName	Retrieves the user name associated with the base process that initiated the activity in which the current object is executing.
Note   When an object calls disableCommit, enableCommit, setComplete, or setAbort from within a method, two flags (Done and Consistent) are set in its Context. (See the following table for an explanation.) These flags aren't evaluated by the MTS run-time environment until the object's currently executing method returns to its caller. This means that an object can call these methods any number of times from within one of its own methods, but the last call before the object returns to its client is the one that will be in effect.

Method	Done	Consistent
setAbort	TRUE	FALSE
setComplete	TRUE	TRUE
disableCommit	FALSE	FALSE
enableCommit	FALSE	TRUE
The Done flag, which allows an object to be deactivated and its transaction to commit or abort, is only evaluated after the object returns from the call that first entered its context. For example, suppose client A calls into object B. Object B calls setComplete and then calls into object C (passing it a safe reference for a callback). Object C calls back to object B, and then object B returns to client A. Object B won't be deactivated when it returns to object C; it will be deactivated when it returns to client A.

See Also

Basic Security Methods, Passing Object References, Context Objects, Transactions, Deactivating Objects


Context.createObjectMethod (Visual J++)
createObject Method

Instantiates an MTS object.

Provided By

Context class

IUnknown createObject (String progID);

IUnknown createObject (com.ms.com._Guid rclsid)

Parameters

progID
[in] The programmatic identifier (ProgID) of the object to be created.

rclsid
[in] Reference to the class identifier (CLSID) of the object to be created.

Return Value

A reference to the IUnknown interface on the newly created object.

Remarks

createObject creates a COM object. However, the object will have context only if its component is registered with MTS.

When you create an object by using createObject, the new object's context is derived from the current object's Context and the declarative properties of the new object's component. The new object always executes within the same activity as the object that created it. If the current object has a transaction, the transaction attribute of the new object's component determines whether or not the new object will execute within the scope of that transaction.

If the component's transaction attribute is set to either Requires a transaction or Supports transactions, the new object inherits its creator's transaction. If the component's transaction attribute is set to Requires a new transaction, MTS initiates a new transaction for the new object. If the component's transaction attribute is set to Does not support transactions, the new object doesn't execute under any transaction.

MTS always uses standard marshaling. Even if a component exposes the IMarshal interface, its IMarshal methods will never be called by the MTS run-time environment.

You can't create MTS objects as part of an aggregation.

See Also

Creating MTS Objects, Transaction Attributes, MTS Component Requirements


Context.disableCommit Method (Visual J++)
disableCommit Method

Declares that the object's transactional updates are inconsistent and can't be committed in their present state.

Provided By

Context class

void disableCommit ( );

Remarks

An object that invokes disableCommit is stateful.

You can use the disableCommit method to prevent a transaction from committing prematurely between method calls in a stateful object. When an object invokes disableCommit, it indicates that its work is inconsistent and that it can't complete its work until it receives further method invocations from the client. It also indicates that it needs to maintain its state to perform that work. This prevents the MTS run-time environment from deactivating the object and reclaiming its resources on return from a method call. Once an object has called disableCommit, if a client attempts to commit the transaction before the object has called enableCommit or setComplete, the transaction will abort.

For example, suppose you have a General Ledger component that updates a database. A client makes multiple calls to a General Ledger object to post entries to various accounts. There's an integrity constraint that says the debits must equal the credits when the final method invocation returns, or the transaction must abort. The General Ledger object has an initialization method in which the client informs it of the sequence of calls the client is going to make, and the General Ledger object calls disableCommit. The object maintains its state between calls so that after the final call in the sequence is made the object can make sure the integrity constraint is satisfied before allowing its work to be committed.

See Also

Transactions


Context.enableCommit Method (Visual J++)
enableCommit Method

Declares that the current object's work is not necessarily finished, but that its transactional updates are consistent and could be committed in their present form.

Provided By

Context class

void enableCommit ( );

Remarks

When an object calls enableCommit, it allows the transaction in which it's participating to be committed, but it maintains its internal state across calls from its clients until it calls etComplete or setAbort or until the transaction completes.

enableCommit is the default state when an object is activated. This is why an object should always call setComplete or setAbort before returning from a method, unless you want the object to maintain its internal state for the next call from a client.

See Also

Transactions


Context.getProperty Method (Visual J++)
getProperty Method

Returns a context object property.

Provided By

Context class

Variant getProperty(
String propertyName);

Parameters

propertyName
[in] The name of the context object property to be retrieved.

Return Value

The requested context object property.

Remarks

You can use getProperty to retrieve the following Microsoft Internet Information Server (IIS) intrinsic objects:

•	Request

•	Response

•	Server

•	Application

•	Session

For more information, see the IIS documentation.

To retrieve an IIS object, use the getDispatch method of returned Variant and cast this value to the interface to the IIS object (for example, IReponse for the Response object).

Note   Context properties are not available in MTS 1.0 server processes.


Context.getPropertyNames Method (Visual J++)
getPropertyNames Method

Returns the names of the context object properties.

Provided By

Context class

String[] getPropertyNames ( );

Return Value

An array of context object property names.


Context.isCallerInRole Method (Visual J++)
isCallerInRole Method

Indicates whether an object's direct caller is in a specified role (either individually or as part of a group).

Provided By

Context class

boolean isCallerInRole (

String role

);

Parameters

role
[in] The name of the role in which you want to determine whether the caller is acting.

Return Values

true
Either the caller is in the specified role, or security is not enabled.

false
The caller is not in the specified role.

Remarks

You use this method to determine whether the direct caller of the currently executing method is associated with a specific role. A role is a symbolic name that represents a user or group of users who have specific access permissions to all components in a given package. Developers define roles when they create a component, and roles are mapped to individual users or groups at deployment time.

isCallerInRole only applies to the direct caller of the currently executing method. (The direct caller is the process calling into the current server process. It can be either a base client process or a server process.) isCallerInRole doesn't apply to the process that initiated the call sequence from which the current method was called, or to any other callers in that sequence.

Because isCallerInRole returns true when the object that invokes it is executing in a client's process, it's a good idea to call isSecurityEnabled before calling isCallerInRole. If security isn't enabled, isCallerInRole won't return an accurate result.

See Also

Programmatic Security, Basic Security Methods, Secured Components


Context.isInTransaction Method (Visual J++)
isInTransaction Method

Indicates whether the current object is executing in a transaction.

Provided By

Context class

boolean isInTransaction ( );

Return Values

true
The current object is executing within a transaction.

false
The current object is not executing within a transaction.

Remarks

You can use this method to make sure that an object that requires a transaction never runs without one. For example, if a component that requires a transaction is improperly configured in the MTS Explorer, you can use this method to determine that the object doesn't have a transaction. Then you can return an error to alert the user to the problem, or take whatever action is appropriate.

See Also

Transaction Attributes, Transactions


Context.isSecurityEnabled Method (Visual J++)
isSecurityEnabled Method

Indicates whether or not security is enabled for the current object. MTS security is enabled unless the object is running in the client's process.

Provided By

Context class

boolean isSecurityEnabled ( );

Return Values

true
Security is enabled for this object.

false
Security is not enabled for this object.

Remarks

MTS security is enabled only if an object is running in a server process. This could be either because the object's component was configured to run in a client's process, or because the component and the client are in the same package. If the object is running in the client's process, there is no security checking and isSecurityEnabled will always return false.

See Also

Programmatic Security, Basic Security Methods, Secured Components


Context.setAbort Method (Visual J++)
setAbort Method

Declares that the transaction in which the object is executing must be aborted, and that the object should be deactivated on returning from the currently executing method call.

Provided By

Context class

void setAbort ( );

Remarks

The object is deactivated automatically on return from the method in which it called setAbort. If the object is the root of an automatic transaction, MTS aborts the transaction. If the object is transactional, but not the root of an automatic transaction, the transaction in which it's participating is doomed to abort. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

You can call setAbort in error handlers to ensure that a transaction aborts when an error occurs. You can also call setAbort at the beginning of a method to protect your object from committing prematurely in the event of an unexpected return and then call setComplete just before the method returns, if all goes well.

See Also

Transactions, Context Objects, Deactivating Objects


Context.setComplete Method (Visual J++)
setComplete Method

Declares that the current object has completed its work and should be deactivated when the currently executing method returns to the client. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed.

Provided By

Context class

void setComplete ( );

Remarks

The object is deactivated automatically on return from the method in which it called setComplete. If the object is the root of an automatic transaction, MTS attempts to commit the transaction. However, if any object that was participating in the transaction has called setAbort, or has called disableCommit and has not subsequently called enableCommit or setComplete, the transaction will be aborted. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

If an object doesn't need to maintain its state after it returns from a method call, it should call setComplete so that it can be automatically deactivated as soon as it returns and its resources can be reclaimed.

See Also

Transactions, Context Objects, Deactivating Objects


IObjectContextActivity Interface (Visual C++)
IObjectContextActivity Interface

The IObjectContextActivity interface is used to retrieve a unique identifier associated with the current activity. This activity identifier is a GUID, and is only valid for the lifetime of the current activity.

Remarks

The header file for the IObjectContextActivity is mtx.h. You must also link mtxguid.lib to your project to use this interface.

You obtain a reference to an object's IObjectContextActivity interface by calling QueryInterface on the object's ObjectContext. For example:

m_pIObjectContext->QueryInterface

    (IID_IObjectContextActivity,

    (void**)&m_pIObjectContextActivity));

The IObjectContextActivity interface provides the following methods.

Method	Description
GetActivityId	Retrieves the GUID associated with the current activity.


IObjectContextActivity::GetActivityId Method (Visual C++)
IObjectContextActivity::GetActivityId Method

Retrieves the GUID associated with the current activity.

Provided By

IObjectContextActivity

HRESULT IObjectContextActivity::GetActivityId(
GUID * pActivityId);

Parameters

pActivityId
[out] A reference to the GUID associated with the current activity.

Return Values

S_OK
The GUID of the current activity is returned in the parameter pActivityId.

E_INVALIDARG
The argument passed in the pActivityId parameter is a NULL pointer.

E_UNEXPECTED
An unexpected error occurred.

Example


IObjectContextActivity::GetActivityId Method Example (Visual C++)
GetActivityId Method Example

#include <mtx.h>

HRESULT hr = S_OK;

IObjectContext *pIObjectContext = NULL;

IObjectContextActivity *pIObjectContextActivity = NULL;

GUID activityId;

// Get object context

hr = GetObjectContext(&pIObjectContext);

// Get IObjectContextActivity interface

hr = pIObjectContext->

    QueryInterface(IID_IObjectContextActivity,

    (void**)&pIObjectContextActivity);

// Use IObjectContextActivity to retrieve

// the activity GUID.

hr = pIObjectContextActivity->

    GetActivityId(&activityId);

// Do something with the activity GUID here.

// Release the IObjectContextActivity

// and the IObjectContext pointers

pIObjectContextActivity->Release();

pIObjectContext->Release();


SharedPropertyGroupManager Object (Visual Basic)
SharedPropertyGroupManager Object

The SharedPropertyGroupManager object is used to create shared property groups and to obtain access to existing shared property groups.

Remarks

To use the SharedPropertyGroupManager object, you must set a reference to the Shared Property Manager Type Library (mtxspm.dll).

You can access the SharedPropertyGroupManager object by using either the CreateObject function or the CreateInstance method of the ObjectContext object. It makes no difference which you use.

The Shared Property Manager is a resource dispenser that you can use to share state among multiple objects within a server process. You can't use global variables in a distributed environment because of concurrency and name collision issues. The Shared Property Manager eliminates name collisions by providing shared property groups, which establish unique name spaces for the shared properties they contain. The Shared Property Manager also implements locks and semaphores to protect shared properties from simultaneous access, which could result in lost updates and could leave the properties in an unpredictable state.

Shared properties can be shared only by objects running in the same process. If you want instances of different components to share properties, you have to install the components in the same MTS package. Because there is a risk that administrators will move components from one package to another, it's safest to limit the use of a shared property group to instances of components that are defined in the same DLL.

It's also important for components sharing properties to have the same activation attribute. If two components in the same package have different activation attributes, they generally won't be able to share properties. For example, if one component is configured to run in a client's process and the other is configured to run in a server process, their objects will usually run in different processes, even though they're in the same package.

You should always instantiate the SharedPropertyGroupManager, SharedPropertyGroup, and SharedProperty objects from MTS objects rather than from a base client. If a base client creates shared property groups and properties, the shared properties are inside the base client's process, not in a server process. This means MTS objects can't share the properties unless the objects, too, are running in the client's process (which is generally not a good idea).

Note   When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a non-MTS object doesn't have an ObjectContext.

The SharedPropertyGroupManager object provides the following methods and properties.

Method	Description
CreatePropertyGroup	Creates a new SharedPropertyGroup with a string name as an identifier. If a group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.
Group	Returns a reference to an existing shared property group, given a string name by which it can be identified.
See Also

Sharing State


CreatePropertyGroup Method (Visual Basic)
CreatePropertyGroup Method

Creates and returns a reference to a new shared property group. If a property group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.

Applies To

SharedPropertyGroupManager Object

Syntax

Set propertygroup = sharedpropertygroupmanager.CreatePropertyGroup(name, dwIsoMode, dwrelmode, fExists)

Parameters

propertygroup
An object variable that evaluates to a SharedPropertyGroup object.

sharedpropertygroupmanager
An object variable that represents the SharedPropertyGroupManager with which to create the shared property group.

name
A string expression that contains the name of the shared property group to create.

dwIsoMode
A Long value that specifies the isolation mode for the properties in the new shared property group. See the table that lists dwIsoMode constants later in this topic. If the value of the fExists parameter is set to True on return from this method, the dwIsoMode value you passed in is ignored and the value returned in this parameter is the isolation mode that was assigned when the property group was created.

dwRelMode
A Long value that specifies the release mode for the properties in the new shared property group. See the table that lists dwRelMode constants later in this topic. If the value of the fExists parameter is set to True on return from this method, the dwRelMode value you passed in is ignored and the value returned in this parameter is the release mode that was assigned when the property group was created.

fExists
A Boolean value that's set to True on return from this method if the shared property group specified in the name parameter existed prior to this call, and False if the property group was created by this call.

Settings

The following constants are used in the dwIsoMode parameter to specify the effective isolation mode for a shared property group.

Constant	Value	Description
LockSetGet	0	Default. Locks a property during a Value call, assuring that every get or set operation on a shared property is atomic. This ensures that two clients can't read or write to the same property at the same time, but it doesn't prevent other clients from concurrently accessing other properties in the same group.
LockMethod	1	Locks all of the properties in the shared property group for exclusive use by the caller as long as the caller's current method is executing. This is the appropriate mode to use when there are interdependencies among properties, or in cases where a client may have to update a property immediately after reading it before it can be accessed again.
Note   When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a base client doesn't have an ObjectContext.

The following constants are used in the dwRelMode parameter to specify the effective release mode for a shared property group.

Constant	Value	Description
Standard	0	When all clients have released their references on the property group, the property group is automatically destroyed.
Process	1	The property group isn't destroyed until the process in which it was created has terminated. You must still release all SharedPropertyGroup objects by setting them to Nothing.
Remarks

The CreatePropertyGroup method sets the value in fExists to True if the property group it returns existed prior to the current call. This occurs when another object in the same process has already called CreatePropertyGroup with the same property group name. The CreatePropertyGroup method sets the value in fExists to False if the returned property group was created by the current call.

The isolation mode and release mode are assigned when the property group is originally created and aren't changed if a subsequent call passes different values in these parameters. The caller should always check the value of fExists on return from this method. If fExists is set to True, the caller should check the values returned in dwIsoMode and dwRelMode to determine the isolation and release modes in effect for the property group. For example:

Dim isolationMode As Long

Dim releaseMode As Long

Set isolationMode = LockMethod

Set releaseMode = Process

Set spmGroup = spmMgr.CreatePropertyGroup _

("Counter", isolationMode, releaseMode, fExists)

If fExists Then

If isolationMode <> LockMethod _

Or releaseMode <> Process Then

' Do something appropriate.

EndIf

EndIf

You can pass the constants, LockGetSet or LockMethod as the dwIsoMode argument, and Standard or Process as the dwRelMode argument, directly to the CreatePropertyGroup method. However, when you pass a constant instead of a variable, the CreatePropertyGroup method can't return the isolation and release modes currently in effect if the requested property group already exists.

Note   An object should never attempt to pass a shared property group reference to another object. If the reference is passed outside of the object that acquired it, it's no longer a valid reference.

Example

See Also

Sharing State, IObjectContext Interface, SharedPropertyGroup Object


Group Property (Visual Basic)
Group Property

Returns a reference to an existing shared property group.

Applies To

ISharedPropertyGroupManager Interface

Syntax

Set propertygroup = sharedpropertygroupmanager.Group(name)

Parameters

propertygroup
An object variable that evaluates to a SharedPropertyGroup object.

sharedpropertygroupmanager
An object variable that represents the SharedPropertyGroupManager for the current process.

name
A string expression that contains the name of the shared property group to retrieve.

Example

See Also

Sharing State, SharedPropertyGroupManager Object


SharedPropertyGroup Object (Visual Basic)
SharedPropertyGroup Object

The SharedPropertyGroup object is used to create and access the shared properties in a shared property group.

Remarks

To use the SharedPropertyGroup object, you must set a reference to the Shared Property Manager Type Library (mtxspm.dll)

You can create a SharedPropertyGroup object with the CreatePropertyGroup method of the SharedPropertyGroupManager object.

As with any COM object, you must release a SharedPropertyGroup object when you're finished using it, unless it's a local variable. For example:

Set myPropertyGroup = Nothing

The SharedPropertyGroup object provides the following methods and properties.

Method/Property	Description
CreateProperty	Creates a new shared property identified by a string expression that's unique within its property group.
CreatePropertyByPosition	Creates a new shared property identified by a numeric index within its property group.
Property	Returns a reference to a shared property, given the string name by which the property is identified.
PropertyByPosition	Returns a reference to a shared property, given its numeric index in the shared property group.
See Also

Sharing State, ISharedPropertyGroupManager Object


CreateProperty Method (Visual Basic)
CreateProperty Method

Creates and returns a reference to a new SharedProperty with a specified name. If a shared property by that name already exists, CreateProperty returns a reference to the existing property.

Applies To

SharedPropertyGroup Object

Syntax

Set property = propertygroup.CreateProperty(name, fExists)

Parameters

propertygroup
An object variable that represents the SharedPropertyGroup to which the new SharedProperty object will belong.

property
An object variable that evaluates to a SharedProperty object.

name
A string expression that contains the name of the property to create. You can use this name later to obtain a reference to this property.

fExists
A Boolean value that's set to True on return from this method if the shared property specified in the name parameter existed prior to this call, and False if the property was created by this call.

Remarks

When you create a shared property, its value is set to the default, which is 0.

If you create a shared property with the CreateProperty method, you can access that property only by using Property. You can't assign a numeric index to the same property and then access it by using PropertyByPosition.

The same shared property group can contain some shared property objects that are identified by name and others that are identified by position.

Example

See Also

Sharing State, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method


CreatePropertyByPosition Method (Visual Basic)
CreatePropertyByPosition Method

Creates a new shared property identified by a numeric index that's unique within the property group. If a shared property with the specified index already exists, CreatePropertyByPosition returns a reference to the existing one.

Applies To

SharedPropertyGroup Object

Syntax

Set property = propertygroup.CreatePropertyByPosition (index, fExists)

Parameters

property
An object variable that evaluates to a SharedProperty object.

propertygroup
An object variable that represents the SharedPropertyGroup to which the new SharedProperty object will belong.

index
A Long value that represents the numeric index within the SharedPropertyGroup by which the new property will be referenced. You can use this index later to retrieve the shared property with PropertyByPosition.

fExists
A Boolean value. If fExists is set to True on return from this method, the shared property specified by index existed prior to this call. If it's set to False, the property was created by this call.

Remarks

When you create a shared property, its value is set to the default, which is 0.

If you create a SharedProperty object with the CreatePropertyByPosition method, you can access that property only by using PropertyByPosition. You can't assign a string name to the same property and then access it by using Property. Accessing a property by position is faster than accessing a property by using a string name because it requires less overhead.

The same shared property group can contain some SharedProperty objects that are identified by position and others that are identified by name.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method


CreatePropertyByPosition Method Example (Visual Basic)
CreatePropertyByPosition Method Example

Dim spmMgr As SharedPropertyGroupManager

Dim spmGroup As SharedPropertyGroup

Dim spmPropNextNumber As SharedProperty

Dim bExists As Boolean

Dim iNextValue As Integer

' Create the SharedPropertyGroupManager,

' SharedPropertyGroup, and SharedProperty.

Set spmMgr = CreateObject _

("MTxSpm.SharedPropertyGroupManager.1")

Set spmGroup = spmMgr.CreatePropertyGroup _

("Counter", LockSetGet, Process, bExists)

Set spmPropNextNumber = _

spmGroup.CreatePropertyByPosition(0, bExists)

' Get the next number and increment it.

iNextValue = spmPropNextNumber.Value

spmPropNextNumber.Value = _

spmPropNextNumber.Value + 1


Property Property (Visual Basic)
Property Property

Returns a reference to an existing shared property identified by a string name.

Applies To

SharedPropertyGroup Object

Syntax

Set property = propertygroup.Property(name)

Parameters

propertygroup
An object variable that represents the SharedPropertyGroup to which the SharedProperty object belongs.

property
An object variable that evaluates to a SharedProperty object.

name
A string expression that contains the name of the shared property to retrieve.

Remarks

You can use only Property to access properties that were created with the CreateProperty method. To access properties that were created with the CreatePropertyByPosition method, use PropertyByPosition.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method


Property, Group Properties Example (Visual Basic)
Property, Group Properties Example

Dim spmMgr As SharedPropertyGroupManager

Dim spmGroup As SharedPropertyGroup

Dim spmPropNextNumber As SharedProperty

Dim iNextValue As Integer

' Get the SharedPropertyGroupManager,

' SharedPropertyGroup, and SharedProperty.

Set spmMgr = CreateObject _

("MTxSpm.SharedPropertyGroupManager.1")

Set spmGroup = spmMgr.Group("Counter")

Set spmPropNextNumber = spmGroup.Property("Next")

' Get the next number and increment it.

iNextValue = spmPropNextNumber.Value

spmPropNextNumber.Value = _

spmPropNextNumber.Value + 1


PropertyByPosition Property (Visual Basic)
PropertyByPosition Property

Returns a reference to an existing shared property identified by its numeric index within the property group.

Applies To

SharedPropertyGroup Object

Syntax

Set sharedproperty = propertygroup.PropertyByPosition(index)

Parameters

propertygroup
An object variable that represents the SharedPropertyGroup object to which the SharedProperty object belongs.

sharedproperty
An object variable that evaluates to a SharedProperty object.

index
A Long value that represents the numeric index within the SharedPropertyGroup of the property to retrieve.

Remarks

You can use only PropertyByPosition to access properties that were created with the CreatePropertyByPosition method. To access properties that were created with the CreateProperty method, use Property.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_Property Method


PropertyByPosition Property Example (Visual Basic)
PropertyByPosition Property Example

Dim spmMgr As SharedPropertyGroupManager

Dim spmGroup As SharedPropertyGroup

Dim spmPropNextNumber As SharedProperty

Dim iNextValue As Integer

' Get the SharedPropertyGroupManager,

' SharedPropertyGroup, and SharedProperty.

Set spmMgr = CreateObject _

("MTxSpm.SharedPropertyGroupManager.1")

Set spmGroup = spmMgr.Group("Counter")

Set spmPropNextNumber = spmGroup.PropertyByPosition(0)

' Get the next number and increment it.

iNextValue = spmPropNextNumber.Value

spmPropNextNumber.Value = _

spmPropNextNumber.Value + 1


SharedProperty Object (Visual Basic)
SharedProperty Object

The SharedProperty object is used to set or retrieve the value of a shared property. A shared property can contain any data type that can be represented by a variant.

Remarks

To use the SharedProperty object, you must set a reference to the Shared Property Manager Type Library (mtxspm.dll).

You can create a SharedProperty object with the CreateProperty method or the CreatePropertyByPosition method.

A SharedProperty object can be created or accessed only from within a SharedPropertyGroup.

As with any COM object, you must release a SharedProperty object when you're finished using it, unless it's a local variable. For example:

Set myProperty = Nothing

The SharedProperty object provides the following property.

Property	Description
Value	Sets or retrieves the value of a shared property.
See Also

Sharing State, MTS Supported Variant Types


Value Property (Visual Basic)
Value Property

Sets or retrieves the value of a shared property.

Applies To

SharedProperty Object

Syntax

property.Value = value

Parameters

property
An object variable that represents a SharedProperty object.

value
A Variant containing the value to assign to the SharedProperty object, or the SharedProperty's current value.

Example

See Also

MTS Supported Variant Types, Sharing State


CreatePropertyGroup Method, CreateGroup Method, Value Property Example (Visual Basic)
CreatePropertyGroup Method, CreateProperty Method, Value Property Example

Dim spmMgr As SharedPropertyGroupManager

Dim spmGroup As SharedPropertyGroup

Dim spmPropNextNumber As SharedProperty

Dim bExists As Boolean

Dim iNextValue As Integer

' Create the SharedPropertyGroupManager,

' SharedPropertyGroup, and SharedProperty.

Set spmMgr = CreateObject _

("MTxSpm.SharedPropertyGroupManager.1")

Set spmGroup = spmMgr.CreatePropertyGroup _

("Counter", LockSetGet, Process, bExists)

Set spmPropNextNumber = _

spmGroup.CreateProperty("Next", bExists)

' Get the next number and increment it.

iNextValue = spmPropNextNumber.Value

spmPropNextNumber.Value = _

spmPropNextNumber.Value + 1


ISharedPropertyGroupManager Interface (Visual C++)
ISharedPropertyGroupManager Interface

The ISharedPropertyGroupManager interface is used to create shared property groups and to obtain access to existing shared property groups.

Remarks

The header file for the ISharedPropertyGroupManager interface is mtxspm.h. You must also link mtxguid.lib to your project to use this interface.

You can access the ISharedPropertyGroupManager interface by creating an instance of the SharedPropertyGroupManager by using either IObjectContext::CreateInstance or CoCreateInstance. It makes no difference which you use.

CreateInstance method of the ObjectContext object. It makes no difference which you use.

The Shared Property Manager is a resource dispenser that you can use to share state among multiple objects within a server process. You can't use global variables in a distributed environment because of concurrency and name collision issues. The Shared Property Manager eliminates name collisions by providing shared property groups, which establish unique name spaces for the shared properties they contain. The Shared Property Manager also implements locks and semaphores to protect shared properties from simultaneous access, which could result in lost updates and could leave the properties in an unpredictable state.

Shared properties can be shared only by objects running in the same process. If you want instances of different components to share properties, you have to install the components in the same MTS package. Because there is a risk that administrators will move components from one package to another, it's safest to limit the use of a shared property group to instances of components that are defined in the same DLL.

It's also important for components sharing properties to have the same activation attribute. If two components in the same package have different activation attributes, they generally won't be able to share properties. For example, if one component is configured to run in a client's process and the other is configured to run in a server process, their objects will usually run in different processes, even though they're in the same package.

You should always instantiate the SharedPropertyGroupManager, SharedPropertyGroup, and SharedProperty objects from MTS objects rather than from a base client. If a base client creates shared property groups and properties, the shared properties are inside the base client's process, not in a server process. This means MTS objects can't share the properties unless the objects, too, are running in the client's process (which is generally not a good idea).

Note   When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a non-MTS object doesn't have an ObjectContext.

The ISharedPropertyGroupManager interface exposes the following methods and properties.

Method	Description
CreatePropertyGroup	Creates a new SharedPropertyGroup with a string name as an identifier. If a group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.
get_Group	Returns a reference to an existing shared property group, given a string name by which it can be identified.
get__NewEnum	Returns a reference to an enumerator that iterates through a list of all the shared property groups in a given process.
See Also

Sharing State


ISharedPropertyGroupManager::CreatePropertyGroup Method (Visual C++)
ISharedPropertyGroupManager::CreatePropertyGroup Method

Creates and returns a reference to a new shared property group. If a property group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.

Provided By

ISharedPropertyGroupManager Interface

HRESULT ISharedPropertyGroup::CreatePropertyGroup (

BSTR name,

LONG* plIsoMode,

LONG* plRelMode,

VARIANT_BOOL* pfExists,

ISharedPropertyGroup** ppGroup,

);

Parameters

name
[in] The name of the shared property group to create.

plIsoMode
[in, out] A reference to a LONG that specifies the isolation mode for the properties in the new shared property group. See the table that lists plIsoMode constants later in this topic. If the value of the pfExists parameter is set to VARIANT_TRUE on return from this method, the plIsoMode value you passed in is ignored and the value returned in this parameter is the isolation mode that was assigned when the property group was created.

plRelMode
[in, out] A reference to a LONG that specifies the release mode for the properties in the new shared property group. See the table that lists plRelMode constants later in this topic. If the value of the pfExists parameter is set to VARIANT_TRUE on return from this method, the plRelMode value you passed in is ignored and the value returned in this parameter is the release mode that was assigned when the property group was created.

pfExists
[out] A reference to a BOOL that's set to VARIANT_TRUE on return from this method if the shared property group specified in the name parameter existed prior to this call, and VARIANT_FALSE if the property group was created by this call.

ppGroup
[out] A reference to a shared property group identified by the BSTR passed in the name parameter, or NULL if an error is encountered.

Settings

The following constants are used in the plIsoMode parameter to specify the effective isolation mode for a shared property group.

Constant	Value	Description
LockSetGet	0	Default. Locks a property during a get_Value or put_Valuecall, assuring that every get or set operation on a shared property is atomic. This ensures that two clients can't read or write to the same property at the same time, but it doesn't prevent other clients from concurrently accessing other properties in the same group.
LockMethod	1	Locks all of the properties in the shared property group for exclusive use by the caller as long as the caller's current method is executing. This is the appropriate mode to use when there are interdependencies among properties, or in cases where a client may have to update a property immediately after reading it before it can be accessed again.
Note   When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a base client doesn't have an ObjectContext.

The following constants are used in the plRelMode parameter to specify the effective release mode for a shared property group.

Constant	Value	Description
Standard	0	When all clients have released their references on the property group, the property group is automatically destroyed. (This is the default COM mode.)
Process	1	The property group isn't destroyed until the process in which it was created has terminated.  (Objects that hold references on a property group must still call Release on their references).
Return Values

S_OK
A reference to the shared property group specified in the name parameter is returned in the ppGroup parameter.

CONTEXT_E_NOCONTEXT
The caller isn't executing under the MTS run-time environment. A caller must be executing under MTS to use the Shared Property Manager.

E_INVALIDARG
At least one of the parameters is invalid, or the same object is attempting to create the same property group more than once.

Remarks

The CreatePropertyGroup method sets the value in pfExists to VARIANT_TRUE if the property group it returns in the ppGroup parameter existed prior to the current call. This occurs when another object in the same process has already called CreatePropertyGroup with the same property group name. The CreatePropertyGroup method sets the value in pfExists to  VARIANT_FALSE if the returned property group was created by the current call.

The isolation mode and release mode are assigned when the property group is originally created and aren't changed if a subsequent call passes different values in these parameters. The caller should always check the value of pfExists on return from this method. If pfExists is set to  VARIANT_TRUE, the caller should check the values returned in plIsoMode and plRelMode to determine the isolation and release modes in effect for the property group. For example:

hr = pPropGpMgr->CreatePropertyGroup(stName,

&lIsolationMode, &lReleaseMode, &fAlreadyExists,

&pPropGp);

if (fAlreadyExists) {

if ((lIsolationMode != LockMethod) ||

(lReleaseMode != Process)) {

// Do something appropriate.

}

}

If*

Note   An object should never attempt to pass a shared property group reference to another object. If the reference is passed outside of the object that acquired it, it's no longer a valid reference.

Example

See Also

Sharing State, IObjectContext Interface, ISharedPropertyGroup Interface


ISharedPropertyGroup::get_Group Method (Visual C++)
ISharedPropertyGroupManager::get_Group Method

Returns a reference to an existing shared property group.

Provided By

ISharedPropertyGroupManager Interface

HRESULT ISharedPropertyGroupManager::get_Group (

BSTR name,

ISharedPropertyGroup** ppGroup,

);

Parameters

name
[in] The name of the shared property group to retrieve.

ppGroup
[out] A reference to the shared property group specified in the name parameter, or NULL if the property group doesn't exist.

Return Values

S_OK
The shared property group exists, and a reference to it is returned in the ppGroup parameter.

E_INVALIDARG
The shared property group with the name specified in the name parameter doesn't exist.

Example

See Also

Sharing State, ISharedPropertyGroupManager Interface


ISharedPropertyGroupManager::get__NewEnum Method (Visual C++)
ISharedPropertyGroupManager::get__NewEnum Method

Returns a reference to an enumerator that you can use to iterate through all the shared property groups in a process.

Provided By

ISharedPropertyGroupManager Interface

HRESULT ISharedPropertyGroupManager::get__NewEnum (

IUnknown** ppEnumerator

);

Parameters

ppEnumerator
[out] A reference to the IUnknown interface on a new enumerator object that you can use to iterate through the list of all the shared property groups in the process.

Return Values

S_OK
A reference to the requested enumerator is returned in the ppEnumerator parameter.

Remarks

You use the get__NewEnum method to obtain a reference to an enumerator object. You should immediately call QueryInterface on the returned IUnknown for the IEnumVARIANT interface. This interface exposes several methods you can use to iterate through a list of BSTRs representing shared property group names. Once you have a name, you can use the get_Group method to obtain a reference to the shared property group it represents.

As with any COM object, you must release an enumerator object when you're finished using it. When you enumerate the shared property groups, all groups will be included. However, if you then call CreatePropertyGroup to add a new group, the existing enumerator won't include the new group even if you call Reset or Clone. To include the new group, you must create a new enumerator by calling get__NewEnum again.

Note   get__NewEnum has two underscore characters between get and NewEnum.

Example

See Also

ISharedPropertyGroupManager::get_Group Method, ISharedPropertyGroup Interface


ISharedPropertyGroupManager::get_NewEnum Method Example (Visual C++)
ISharedPropertyGroupManager::get__NewEnum Method Example

#include <mtxspm.h>

ISharedPropertyGroupManager* pspgm = NULL;

IUnknown* pUnknown = NULL;

IEnumVARIANT* pEnum = NULL;

VARIANT v;

ULONG cElementsFetched;

int i;

HRESULT hr;

// Get the enumerator object.

hr = pspgm->get__NewEnum(&pUnknown);

// Query for the IEnumVARIANT interface.

hr = pUnknown->QueryInterface(IID_IEnumVARIANT, (void**) &pEnum);

// Use the enumerator to iterate through

// the property group names.

for(i = 0; i < 10; i++)

{

VariantInit(&v);

pEnum->Next(1, &v, &cElementsFetched);

// Do something with the returned

// property group names.

}


ISharedPropertyGroup Interface (Visual C++)
ISharedPropertyGroup Interface

The ISharedPropertyGroup interface is used to create and access the shared properties in a shared property group.

Remarks

The header file for the ISharedPropertyGroup interface is mtxspm.h. You must also link mtxguid.lib to your project to use this interface.

You can access the ISharedPropertyGroup interface by creating a SharedPropertyGroup object with the ISharedPropertyGroupManager::CreatePropertyGroup method.

As with any COM object, you must release a SharedPropertyGroup object when you're finished using it.

The ISharedPropertyGroup interface exposes the following methods.

CreateProperty	Creates a new shared property identified by a string expression that's unique within its property group.
CreatePropertyByPosition	Creates a new shared property identified by a numeric index within its property group.
get_Property	Returns a reference to a shared property, given the string name by which the property is identified.
get_PropertyByPosition	Returns a reference to a shared property, given its numeric index in the shared property group.
See Also

Sharing State, ISharedPropertyGroupManager Interface


ISharedPropertyGroup::CreateProperty Method (Visual C++)
ISharedPropertyGroup::CreateProperty Method

Creates and returns a reference to a new SharedProperty with a specified name. If a shared property by that name already exists, CreateProperty returns a reference to the existing property.

Provided By

ISharedPropertyGroup Interface

HRESULT ISharedPropertyGroup::CreateProperty (

BSTR name,

VARIANT_BOOL* pfExists;

ISharedProperty** ppProp,

);

Parameters

name
[in] The name of the property to create. You can use this name later to obtain a reference to this property by using the get_Property method.

pfExists
[out] A reference to a Boolean value that's set to VARIANT_TRUE on return from this method if the shared property specified in the name parameter existed prior to this call, and VARIANT_FALSE if the property was created by this call.

ppProp
[out] A reference to a SharedProperty object with the name specified in the name parameter, or NULL if an error is encountered.

Return Values

S_OK
A reference to a shared property with the name specified in the name parameter is returned in the parameter ppProp.

E_INVALIDARG
One or more of the arguments passed in is invalid.

Remarks

When you create a shared property, its value is set to the default, which is a VARIANT of type VT_I4, with a value of 0.

If you create a shared property with the CreateProperty method, you can access that property only by using the get_Property method. You can't assign a numeric index to the same property and then access it by using the get_PropertyByPosition method.

The same shared property group can contain some shared property objects that are identified by name and others that are identified by position.

Example

See Also

Sharing State, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method


ISharedPropertyGroup::CreatePropertyByPosition Method (Visual C++)
ISharedPropertyGroup::CreatePropertyByPosition Method

Creates a new shared property identified by a numeric index that's unique within the property group. If a shared property with the specified index already exists, CreatePropertyByPosition returns a reference to the existing one.

Provided By

ISharedPropertyGroup Interface

HRESULT ISharedPropertyGroup::CreatePropertyByPosition (

INT index,

VARIANT_BOOL* pfExists;

ISharedProperty** ppProp,

);

Parameters

index
[in] The numeric index within the SharedPropertyGroup by which the new property will be referenced. You can use this index later to retrieve the shared property with the get_PropertyByPosition method.

pfExists
[out] A reference to a Boolean value. If pfExists is set to VARIANT_TRUE on return from this method, the shared property specified by index existed prior to this call. If it's set to VARIANT_FALSE, the property was created by this call.

ppProp
[out] A reference to a shared property object identified by the numeric index passed in the index parameter, or NULL if an error is encountered.

Return Values

S_OK
A reference to the shared property occupying the position specified in the index parameter is returned in the ppProp parameter.

E_INVALIDARG
One or more of the arguments passed in is invalid.

Remarks

When you create a shared property, its value is set to the default, which is a VARIANT of type VT_I4, with a value of 0.

If you create a SharedProperty object with the CreatePropertyByPosition method, you can access that property only by using the get_PropertyByPosition method. You can't assign a string name to the same property and then access it by using the get_Property method. Accessing a property by position is faster than accessing a property by using a string name because it requires less overhead.

The same shared property group can contain some SharedProperty objects that are identified by position and others that are identified by name.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method


ISharedPropertyGroup::CreatePropertyByPosition Method Example (Visual C++)
ISharedPropertyGroup::CreatePropertyByPosition Method Example

#include <mtx.h>

#include <mtxspm.h>

IObjectContext* pObjectContext = NULL;

ISharedPropertyGroupManager* pPropGpMgr = NULL;

ISharedPropertyGroup* pPropGp = NULL;

ISharedProperty* pPropNextNum = NULL;

VARIANT_BOOL fAlreadyExists = VARIANT_FALSE;

LONG lIsolationMode = LockMethod;

LONG lReleaseMode = Process;

BSTR stName;

VARIANT vNext;

LONG lNextValue = 0L;

HRESULT hr = S_OK;

hr = GetObjectContext(&pObjectContext);

// Create the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

hr = pObjectContext->CreateInstance

(CLSID_SharedPropertyGroupManager,

IID_ISharedPropertyGroupManager,

(void**)&pPropGpMgr);

stName = SysAllocString(L"Counter");

hr = pPropGpMgr->CreatePropertyGroup(stName,

&lIsolationMode, &lReleaseMode, &fAlreadyExists,

&pPropGp);

SysFreeString(stName);

hr = pPropGp->CreatePropertyByPosition

(0, &fAlreadyExists, &pPropNextNum);

// Get the next number and increment the counter.

VariantInit(&vNext);

vNext.vt = VT_I4;

hr = pPropNextNum->get_Value(&vNext);

lNextValue = vNext.lVal++;

hr = pPropNextNum->put_Value(vNext);


ISharedPropertyGroup::get_Property Method (Visual C++)
ISharedPropertyGroup::get_Property Method

Returns a reference to an existing shared property identified by a string name.

Provided By

ISharedPropertyGroup Interface

HRESULT ISharedPropertyGroup::get_Property (

BSTR name,

ISharedProperty** ppProperty,

);

Parameters

name
[in] The name of the shared property to retrieve.

ppProperty
[out] A reference to the shared property specified in the name parameter, or NULL if the property doesn't exist.

Return Values

S_OK
The shared property specified by name was found and a reference to it is returned in the ppProperty parameter.

E_INVALIDARG
Either the argument passed in the ppProperty parameter was a null pointer, or there is no property in the shared property group with the name specified in the name parameter.

Remarks

You can use only the get_Property method to access properties that were created with the CreateProperty method. To access properties that were created with the CreatePropertyByPosition method, use the get_PropertyByPosition method.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method


ISharedPropertyGroupManager::get_Group, ISharedPropertyGroup::get_Property Methods Example (Visual C++)
ISharedPropertyGroupManager::get_Group, ISharedPropertyGroup::get_Property Methods Example

#include <mtx.h>

#include <mtxspm.h>

IObjectContext* pObjectContext = NULL;

ISharedPropertyGroupManager* pPropGpMgr = NULL;

ISharedPropertyGroup* pPropGp = NULL;

ISharedProperty* pPropNextNum = NULL;

BSTR stName, stNextNumber;

VARIANT vNext;

LONG lNextValue = 0L;

HRESULT hr = S_OK;

hr = GetObjectContext(&pObjectContext);

// Get the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

hr = pObjectContext->CreateInstance

(CLSID_SharedPropertyGroupManager,

IID_ISharedPropertyGroupManager,

(void**)&pPropGpMgr);

stName = SysAllocString(L"Counter");

hr = pPropGpMgr->get_Group(stName, &pPropGp);

SysFreeString(stName);

stNextNumber = SysAllocString(L"NextNum");

hr = pPropGp->get_Property

(stNextNumber, &pPropNextNum);

SysFreeString(stNextNumber);

// Get the next number and increment the counter.

VariantInit(&vNext);

vNext.vt = VT_I4;

hr = pPropNextNum->get_Value(&vNext);

lNextValue = vNext.lVal++;

hr = pPropNextNum->put_Value(vNext);


ISharedPropertyGroup::get_PropertyByPosition Method (Visual C++)
ISharedPropertyGroup::get_PropertyByPosition Method

Returns a reference to an existing shared property identified by its numeric index within the property group.

Provided By

ISharedPropertyGroup Interface

HRESULT ISharedPropertyGroup::get_PropertyByPosition (

INT index,

ISharedProperty** ppProperty,

);

Parameters

index
[in] The numeric index within the SharedPropertyGroup of the property to retrieve.

ppProperty
[out] A reference to the shared property specified by the index parameter, or NULL if the property doesn't exist.

Return Values

S_OK
The shared property specified by index was found and a reference to it is returned in the ppProperty parameter.

E_INVALIDARG
Either the argument passed in the ppProperty parameter was a null pointer, or there is no property in the shared property group with the index number specified in the index parameter.

Remarks

You can use only the get_PropertyByPosition method to access properties that were created with the CreatePropertyByPosition method. To access properties that were created with the CreateProperty method, use the get_Property method.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_Property Method


ISharedPropertyGroup::get_PropertyByPosition Method Example (Visual C++)
ISharedPropertyGroup::get_PropertyByPosition Method Example

#include <mtx.h>

#include <mtxspm.h>

IObjectContext* pObjectContext = NULL;

ISharedPropertyGroupManager* pPropGpMgr = NULL;

ISharedPropertyGroup* pPropGp = NULL;

ISharedProperty* pPropNextNum = NULL;

BSTR stName;

VARIANT vNext;

LONG lNextValue = 0L;

HRESULT hr = S_OK;

hr = GetObjectContext(&pObjectContext);

// Get the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

hr = pObjectContext->CreateInstance

(CLSID_SharedPropertyGroupManager,

IID_ISharedPropertyGroupManager,

(void**)&pPropGpMgr);

stName = SysAllocString(L"Counter");

hr = pPropGpMgr->get_Group(stName, &pPropGp);

SysFreeString(stName);

hr = pPropGp->get_PropertyByPosition

(0, &pPropNextNum);

// Get the next number and increment the counter.

VariantInit(&vNext);

vNext.vt = VT_I4;

hr = pPropNextNum->get_Value(&vNext);

lNextValue = vNext.lVal++;

hr = pPropNextNum->put_Value(vNext);


ISharedProperty Interface (Visual C++)
ISharedProperty Interface

The ISharedProperty interface is used to set or retrieve the value of a shared property. A shared property can contain any data type that can be represented by a variant.

Remarks

The header file for the ISharedProperty interface is mtxspm.h. You must also link mtxguid.lib to your project to use this interface.

You can access the ISharedProperty interface by creating a SharedProperty object with the ISharedPropertyGroup::CreateProperty method or the ISharedPropertyGroup::CreatePropertyByPosition method.

A SharedProperty object can be created or accessed only from within a SharedPropertyGroup.

As with any COM object, you must release a SharedProperty object when you're finished using it.

The ISharedProperty interface exposes the following methods.

Method	Description
get_Value	Retrieves the value of a shared property.
put_Value	Sets the value of a shared property.
See Also

Sharing State, MTS Supported Variant Types


ISharedProperty::get_Value Method (Visual C++)
ISharedProperty::get_Value Method

Retrieves the value of a shared property.

Provided By

ISharedProperty Interface

HRESULT ISharedProperty::get_Value (

VARIANT* pVal

);

Parameters

pVal
[out] A reference to a variant in which the value of the shared property will be returned.

Return Values

S_OK
A reference to a VARIANT containing the value of the shared property is returned in the pVal parameter.

E_INVALIDARG
The argument passed in the pval parameter is invalid.

Example

See Also

MTS Supported Variant Types, Sharing State


ISharedProperty::put_Value Method (Visual C++)
ISharedProperty::put_Value Method

Assigns a value to a shared property.

Provided By

ISharedProperty Interface

HRESULT ISharedProperty::put_Value (

VARIANT value

);

Parameters

value
[in] A VARIANT containing the value to assign to the SharedProperty object.

Return Values

S_OK
The shared property's value has been set to value.

E_INVALIDARG
The argument passed in the value parameter has the VT_BYREF bit set.

DISP_E_ARRAYISLOCKED
The argument passed in the value parameter contains an array that's locked.

DISP_E_BADVARTYPE
The argument passed in the value parameter isn't a valid VARIANT type.

Example

See Also

MTS Supported Variant Types, Sharing State


CreatePropertyGroup, CreateProperty, put_Value, get_Value Methods Example (Visual C++)
CreatePropertyGroup, CreateProperty, put_Value, get_Value Methods Example

#include <mtx.h>

#include <mtxspm.h>

IObjectContext* pObjectContext = NULL;

ISharedPropertyGroupManager* pPropGpMgr = NULL;

ISharedPropertyGroup* pPropGp = NULL;

ISharedProperty* pPropNextNum = NULL;

VARIANT_BOOL fAlreadyExists = VARIANT_FALSE;

LONG lIsolationMode = LockMethod;

LONG lReleaseMode = Process;

LONG lNextValue = 0L;

BSTR stName, stNextNumber;

VARIANT vNext;

HRESULT hr = S_OK;

hr = GetObjectContext(&pObjectContext);

// Create the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

hr = pObjectContext->CreateInstance

(CLSID_SharedPropertyGroupManager,

IID_ISharedPropertyGroupManager,

(void**)&pPropGpMgr);

stName = SysAllocString(L"Counter");

hr = pPropGpMgr->CreatePropertyGroup(stName,

&lIsolationMode, &lReleaseMode, &fAlreadyExists,

&pPropGp);

SysFreeString(stName);

stNextNumber = SysAllocString(L"NextNum");

hr = pPropGp->CreateProperty

(stNextNumber, &fAlreadyExists, &pPropNextNum);

SysFreeString(stNextNumber);

// Get the next number and increment the counter.

VariantInit(&vNext);

vNext.vt = VT_I4;

hr = pPropNextNum->get_Value(&vNext);

lNextValue = vNext.lVal++;

hr = pPropNextNum->put_Value(vNext);


ISharedPropertyGroupManager Interface (Visual J++)
ISharedPropertyGroupManager Interface

The ISharedPropertyGroupManager interface is used to create shared property groups and to obtain access to existing shared property groups.

Remarks

The ISharedPropertyGroupManager interface is declared in the package com.ms.mtx.

You can access the ISharedPropertyGroupManager interface by creating an instance of the SharedPropertyGroupManager by using either IObjectContext.CreateInstance or new SharedPropertyGroupManager. It makes no difference which you use.

CreateInstance method of the ObjectContext object. It makes no difference which you use.

The Shared Property Manager is a resource dispenser that you can use to share state among multiple objects within a server process. You can't use global variables in a distributed environment because of concurrency and name collision issues. The Shared Property Manager eliminates name collisions by providing shared property groups, which establish unique name spaces for the shared properties they contain. The Shared Property Manager also implements locks and semaphores to protect shared properties from simultaneous access, which could result in lost updates and could leave the properties in an unpredictable state.

Shared properties can be shared only by objects running in the same process. If you want instances of different components to share properties, you have to install the components in the same MTS package. Because there is a risk that administrators will move components from one package to another, it's safest to limit the use of a shared property group to instances of components that are defined in the same DLL.

It's also important for components sharing properties to have the same activation attribute. If two components in the same package have different activation attributes, they generally won't be able to share properties. For example, if one component is configured to run in a client's process and the other is configured to run in a server process, their objects will usually run in different processes, even though they're in the same package.

You should always instantiate the SharedPropertyGroupManager, SharedPropertyGroup, and SharedProperty objects from MTS objects rather than from a base client. If a base client creates shared property groups and properties, the shared properties are inside the base client's process, not in a server process. This means MTS objects can't share the properties unless the objects, too, are running in the client's process (which is generally not a good idea).

Note   When you set the isolation mode to LOCKMODE_METHOD, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a non-MTS object doesn't have an ObjectContext.

The ISharedPropertyGroupManager interface exposes the following methods and properties.

Method	Description
CreatePropertyGroup	Creates a new SharedPropertyGroup with a string name as an identifier. If a group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.
getGroup	Returns a reference to an existing shared property group, given a string name by which it can be identified.
get_NewEnum	Returns a reference to an enumerator that iterates through a list of all the shared property groups in a given process.
See Also

Sharing State


ISharedPropertyGroupManager.CreatePropertyGroup Method (Visual J++)
ISharedPropertyGroupManager.CreatePropertyGroup Method

Creates and returns a reference to a new shared property group. If a property group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.

Provided By

ISharedPropertyGroupManager Interface

ISharedPropertyGroup CreatePropertyGroup (

String name,

int[] lockmode,

int[]  releasemode,

boolean[] exists,

);

Parameters

name
[in] The name of the shared property group to create.

lockmode
[in, out] An array of one integer that specifies the isolation mode for the properties in the new shared property group. See the table that lists lockmode constants later in this topic. If the value of the exists parameter is set to true on return from this method, the lockmode value you passed in is ignored and the value returned in this parameter is the isolation mode that was assigned when the property group was created.

releasemode
[in, out] An array of one integer that specifies the release mode for the properties in the new shared property group. See the table that lists releasemode constants later in this topic. If the value of the exists parameter is set to true on return from this method, the releasemode value you passed in is ignored and the value returned in this parameter is the release mode that was assigned when the property group was created.

exists
[out] An array of one boolean that's set to true on return from this method if the shared property group specified in the name parameter existed prior to this call, and false if the property group was created by this call.

Settings

The following constants are used in the lockmode parameter to specify the effective isolation mode for a shared property group. These constants are static final members of the ISharedPropertyGroupManager interface.

Constant	Value	Description
LOCKMODE _SETGET	0	Default. Locks a property during a getValue or putValuecall, assuring that every get or set operation on a shared property is atomic. This ensures that two clients can't read or write to the same property at the same time, but it doesn't prevent other clients from concurrently accessing other properties in the same group.
LOCKMODE _METHOD	1	Locks all of the properties in the shared property group for exclusive use by the caller as long as the caller's current method is executing. This is the appropriate mode to use when there are interdependencies among properties, or in cases where a client may have to update a property immediately after reading it before it can be accessed again.
Note   When you set the isolation mode to LOCKMODE_METHOD, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a base client doesn't have an ObjectContext.

The following constants are used in the releasemode parameter to specify the effective release mode for a shared property group. These constants are static final members of the ISharedPropertyGroupManager interface.

Constant	Value	Description
RELEASE MODE_ STANDARD	0	When all clients have released their references on the property group, the property group is automatically destroyed. (This is the default COM mode.)
RELEASE MODE_ PROCESS	1	The property group isn't destroyed until the process in which it was created has terminated.
Return Value

A reference to a shared property group identified by the string expression passed in the name parameter, or null if an error is encountered.

Remarks

The CreatePropertyGroup method sets the value in exists to true if the property group it returns existed prior to the current call. This occurs when another object in the same process has already called CreatePropertyGroup with the same property group name. The CreatePropertyGroup method sets the value in exists to false if the returned property group was created by the current call.

The isolation mode and release mode are assigned when the property group is originally created and aren't changed if a subsequent call passes different values in these parameters. The caller should always check the value of exists on return from this method. If exists is set to true, the caller should check the values returned in lockmode and releasemode to determine the isolation and release modes in effect for the property group. For example:

propGp = propGpMgr.CreatePropertyGroup

("Counter", aiIsolationMode,

aiReleaseMode, afAlreadyExists);

if (afAlreadyExists[0]) {

if ((aiIsolationMode[0] !=

ISharedPropertyGroupManager.LOCKMODE_METHOD) ||

(aiReleaseMode[0] ISharedPropertyGroupManager.

RELEASEMODE_PROCESS)) {

// Do something appropriate.

}

}

If*

Note   An object should never attempt to pass a shared property group reference to another object. If the reference is passed outside of the object that acquired it, it's no longer a valid reference.

Example

See Also

Sharing State, IObjectContext Interface, ISharedPropertyGroup Interface


ISharedPropertyGroup.getGroup Method (Visual J++)
ISharedPropertyGroupManager.getGroup Method

Returns a reference to an existing shared property group.

Provided By

ISharedPropertyGroupManager Interface

ISharedPropertyGroup getGroup (

String name,

);

Parameters

name
[in] The name of the shared property group to retrieve.

Return Value

A reference to the shared property group specified in the name parameter, or null if the property group doesn't exist.

Example

See Also

Sharing State, ISharedPropertyGroupManager Interface


ISharedPropertyGroupManager.get_NewEnum Method (Visual J++)
ISharedPropertyGroupManager.get_NewEnum Method

Returns a reference to an enumerator that you can use to iterate through all the shared property groups in a process.

Provided By

ISharedPropertyGroupManager Interface

IUnknown get_NewEnum ( );

Return Value

A reference to the IUnknown interface on a new enumerator object that you can use to iterate through the list of all the shared property groups in the process.

Remarks

You use the get_NewEnum method to obtain a reference to an enumerator object. You should immediately cast the returned value to the IEnumVariant interface. This interface exposes several methods you can use to iterate through a list of string expressions representing shared property group names. Once you have a name, you can use the getGroup method to obtain a reference to the shared property group it represents. When you enumerate the shared property groups, all groups will be included. However, if you then call CreatePropertyGroup to add a new group, the existing enumerator won't include the new group even if you call Reset or Clone. To include the new group, you must create a new enumerator by calling NewEnum again.

Example

See Also

ISharedPropertyGroupManager.getGroup Method, ISharedPropertyGroup Interface


ISharedPropertyGroupManager.get_NewEnum Method Example (Visual J++)
get_NewEnum Method Example

import com.ms.mtx.*;

ISharedPropertyGroupManager spgm = null;

IEnumVariant myEnum = null;

Variant v;

int i;

// Get the enumerator object and

// cast the returned interface to IEnumVariant.

myEnum = (IEnumVariant)spgm.get_NewEnum();

// Use the enumerator to iterate through

// the property group names.

for(i = 0; i < 10; i++){

v = Enum.Next(1);

// Do something with the returned

// property group names.

}


ISharedPropertyGroup Interface (Visual J++)
ISharedPropertyGroup Interface

The ISharedPropertyGroup interface is used to create and access the shared properties in a shared property group.

Remarks

The ISharedPropertyGroup interface is declared in the package com.ms.mtx.

You can access the ISharedPropertyGroup interface by creating a SharedPropertyGroup object with the ISharedPropertyGroupManager.CreatePropertyGroup method.

The ISharedPropertyGroup interface exposes the following methods.

CreateProperty	Creates a new shared property identified by a string expression that's unique within its property group.
CreatePropertyByPosition	Creates a new shared property identified by a numeric index within its property group.
getProperty	Returns a reference to a shared property, given the string name by which the property is identified.
getPropertyByPosition	Returns a reference to a shared property, given its numeric index in the shared property group.
See Also

Sharing State, ISharedPropertyGroupManager Interface


ISharedPropertyGroup.CreateProperty Method (Visual J++)
ISharedPropertyGroup.CreateProperty Method

Creates and returns a reference to a new SharedProperty with a specified name. If a shared property by that name already exists, CreateProperty returns a reference to the existing property.

Provided By

ISharedPropertyGroup Interface

ISharedProperty CreateProperty (

String name,

boolean[] exists;

);

Parameters

name
[in] The name of the property to create. You can use this name later to obtain a reference to this property by using the getProperty method.

exists
[out] An array of one Boolean value that's set to true on return from this method if the shared property specified in the name parameter existed prior to this call, and false if the property was created by this call.

Return Value

A reference to a shared property object with the name specified in the name parameter, or null if an error is encountered.

Remarks

When you create a shared property, its value is set to the default, which is a Variant with an integer value of 0.

If you create a shared property with the CreateProperty method, you can access that property only by using the getProperty method. You can't assign a numeric index to the same property and then access it by using the getPropertyByPosition method.

The same shared property group can contain some shared property objects that are identified by name and others that are identified by position.

Example

See Also

Sharing State, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method


ISharedPropertyGroup.CreatePropertyByPosition Method (Visual J++)
ISharedPropertyGroup.CreatePropertyByPosition Method

Creates a new shared property identified by a numeric index that's unique within the property group. If a shared property with the specified index already exists, CreatePropertyByPosition returns a reference to the existing one.

Provided By

ISharedPropertyGroup Interface

ISharedProperty CreatePropertyByPosition (

int index,

boolean[] exists;

);

Parameters

index
[in] The numeric index within the SharedPropertyGroup by which the new property will be referenced. You can use this index later to retrieve the shared property with the getPropertyByPosition method.

exists
[out] An array of one boolean value. If exists is set to true on return from this method, the shared property specified by index existed prior to this call. If it's set to false, the property was created by this call.

Return Value

A reference to a shared property object that's identified by the numeric index passed in the index parameter, or null if an error is encountered.

Remarks

When you create a shared property, its value is set to the default, which is a Variant with an integer value of 0.

If you create a SharedProperty object with the CreatePropertyByPosition method, you can access that property only by using the getPropertyByPosition method. You can't assign a string name to the same property and then access it by using the getProperty method. Accessing a property by position is faster than accessing a property by using a string name because it requires less overhead.

The same shared property group can contain some SharedProperty objects that are identified by position and others that are identified by name.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method


ISharedPropertyGroup.CreatePropertyByPosition Method Example (Visual J++)
ISharedPropertyGroup.CreatePropertyByPosition Method Example

import com.ms.mtx.*;

ISharedPropertyGroupManager propGpMgr = null;

ISharedPropertyGroup propGp = null;

ISharedProperty propNextNum = null;

Variant vNext;

int iNextValue = 0;

boolean[] afAlreadyExists = new boolean[1];

int[] aiIsolationMode = new int[1];

aiIsolationMode[0] =

ISharedPropertyGroupManager.LOCKMODE_SETGET;

int[] aiReleaseMode = new int[1];

aiReleaseMode[0] =

ISharedPropertyGroupManager.RELEASEMODE_PROCESS;

// Create the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

propGpMgr = new SharedPropertyGroupManager();

propGp = propGpMgr.CreatePropertyGroup

("Counter", aiIsolationMode,

aiReleaseMode, afAlreadyExists);

propNextNum = propGp.CreatePropertyByPosition

(0, fAlreadyExists);

// Get the next number and increment it.

VariantInit(&vNext);

vNext = propNextNum.getValue();

iNextValue = vNext.getInt();

vNext.putInt(iNextValue + 1);

propNextNum.putValue(vNext);


ISharedPropertyGroup.getProperty Method (Visual J++)
ISharedPropertyGroup.getProperty Method

Returns a reference to an existing shared property identified by a string name.

Provided By

ISharedPropertyGroup Interface

ISharedProperty getProperty (

String name,

);

Parameters

name
[in] A string expression that contains the name of the shared property to retrieve.

Return Value

A reference to the shared property specified in the name parameter, or null if the property doesn't exist.

Remarks

You can use only the getProperty method to access properties that were created with the CreateProperty method. To access properties that were created with the CreatePropertyByPosition method, use the getPropertyByPosition method.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method


ISharedPropertyGroupManager.getGroup, ISharedPropertyGroup.getProperty Methods Example (Visual J++)
ISharedPropertyGroupManager.getGroup, ISharedPropertyGroup.getProperty Methods Example

import com.ms.mtx.*;

ISharedPropertyGroupManager propGpMgr = null;

ISharedPropertyGroup propGp = null;

ISharedProperty propNextNum = null;

Variant vNext;

int iNextValue = 0;

// Get the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

propGpMgr = new SharedPropertyGroupManager();

propGp = propGpMgr.getGroup("Counter");

propNextNum = propGp.getProperty("NextNum");

// Get the next number and increment it.

VariantInit(&vNext);

vNext = propNextNum.getValue();

iNextValue = vNext.getInt();

vNext.putInt(iNextValue + 1);

propNextNum.putValue(vNext);


ISharedPropertyGroup.getPropertyByPosition Method (Visual J++)
ISharedPropertyGroup.getPropertyByPosition Method

Returns a reference to an existing shared property identified by its numeric index within the property group.

Provided By

ISharedPropertyGroup Interface

ISharedProperty getPropertyByPosition (

INT index,

);

Parameters

index
[in] The numeric index within the SharedPropertyGroup of the property to retrieve.

Return Value

A reference to the shared property specified by the index parameter, or null if the property doesn't exist.

Remarks

You can use only the getPropertyByPosition method to access properties that were created with the CreatePropertyByPosition method. To access properties that were created with the CreateProperty method, use the getProperty method.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_Property Method


ISharedPropertyGroup.getPropertyByPosition Method Example (Visual J++)
ISharedPropertyGroup.getPropertyByPosition Method Example

import com.ms.mtx.*;

ISharedPropertyGroupManager propGpMgr = null;

ISharedPropertyGroup propGp = null;

ISharedProperty propNextNum = null;

Variant vNext;

int iNextValue = 0;

// Get the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

propGpMgr = new SharedPropertyGroupManager();

propGp = propGpMgr.getGroup("Counter");

propNextNum = propGp.getPropertyByPosition(0);

// Get the next number and increment it.

VariantInit(&vNext);

vNext = propNextNum.getValue();

iNextValue = vNext.getInt();

vNext.putInt(iNextValue + 1);

propNextNum.putValue(vNext);


ISharedProperty Interface (Visual J++)
ISharedProperty Interface

The ISharedProperty interface is used to set or retrieve the value of a shared property. A shared property can contain any data type that can be represented by a variant.

Remarks

The ISharedProperty interface is declared in the package com.ms.mtx.

You can access the ISharedProperty interface by creating a SharedProperty object with the ISharedPropertyGroup.CreateProperty method or the ISharedPropertyGroup.CreatePropertyByPosition method.

A SharedProperty object can be created or accessed only from within a SharedPropertyGroup.

The ISharedProperty interface exposes the following methods.

Method	Description
getValue	Retrieves the value of a shared property.
putValue	Sets the value of a shared property.
See Also

Sharing State, MTS Supported Variant Types


ISharedProperty.getValue Method (Visual J++)
ISharedProperty.getValue Method

Retrieves the value of a shared property.

Provided By

ISharedProperty Interface

Variant getValue ( );

Return Value

A Variant in which the value of the shared property will be returned.

Example

See Also

MTS Supported Variant Types, Sharing State


ISharedProperty.putValue Method (Visual J++)
ISharedProperty.putValue Method

Assigns a value to a shared property.

Provided By

ISharedProperty Interface

void putValue (

Variant value

);

Parameters

value
[in] A Variant containing the value to assign to the SharedProperty object.

Example

See Also

MTS Supported Variant Types, Sharing State


CreatePropertyGroup, CreateProperty, putValue, getValue Methods Example (Visual J++)
CreatePropertyGroup, CreateProperty, putValue, getValue Methods Example

import com.ms.mtx.*;

ISharedPropertyGroupManager propGpMgr = null;

ISharedPropertyGroup propGp = null;

ISharedProperty propNextNum = null;

Variant vNext;

int iNextValue = 0;

boolean[] afAlreadyExists = new boolean[1];

int[] aiIsolationMode = new int[1];

aiIsolationMode[0] =

ISharedPropertyGroupManager.LOCKMODE_SETGET;

int[] aiReleaseMode = new int[1];

aiReleaseMode[0] =

ISharedPropertyGroupManager.RELEASEMODE_PROCESS;

// Create the SharedPropertyGroupManager,

// SharedPropertyGroup, and SharedProperty.

propGpMgr = new SharedPropertyGroupManager();

propGp = propGpMgr.CreatePropertyGroup

("Counter", aiIsolationMode,

aiReleaseMode, afAlreadyExists);

propNextNum = propGp.CreateProperty

("NextNum", afAlreadyExists);

// Get the next number and increment it.

VariantInit(&vNext);

vNext = propNextNum.getValue();

iNextValue = vNext.getInt();

vNext.putInt(iNextValue + 1);

propNextNum.putValue(vNext);


TransactionContext Object (Visual Basic)
TransactionContext Object

The TransactionContext object is used by a base client to compose the work of one or more MTS objects into an atomic transaction and to commit or abort the transaction.

Remarks

To use the TransactionContext object, you must set a reference to the Transaction Context Type Library (txctx.dll).

You can use a TransactionContext object to scope a transaction from a base client. You begin the transaction by instantiating a TransactionContext object, and you end the transaction by calling Commit or Abort on the object. The base client itself never executes within the transaction.

The TransactionContext component is a standard MTS component. The component's transaction attribute is set to Requires a new transaction, which means that a TransactionContext object is always the root of a transaction. When a base client instantiates an object by using the TransactionContext object's CreateInstance method, the new object and its descendants will participate in theTransactionContext object's transaction unless the new object's transaction attribute is set to Requires a new transaction or Does not support transactions.

You could easily write your own TransactionContext component. You would simply create a component that implements the methods Commit, Abort, and CreateInstance, and set the component's transaction attribute to Requires a new transaction. The three methods would do nothing more than call GetObjectContext and invoke their ObjectContext object's SetComplete, SetAbort, and CreateInstance methods, respectively.

Before you use TransactionContext to compose the work of existing components in a transaction, you should consider implementing a separate component that not only composes their work but encapsulates it into a reusable unit. This new component would not only serve the needs of the current base client, but other clients could also use it. In one approach, the base client instantiates a TransactionContext object, calls its CreateInstance method to instantiate other objects, calls various methods on those objects, and finally calls Commit or Abort on the TransactionContext object. In the other approach, you create a new component that requires a transaction. This new component instantiates the other objects using its ObjectContext object's CreateInstance method, calls the relevant methods on those other objects itself, and then calls SetComplete or SetAbort on its ObjectContext when it's done. Using this approach, the base client only needs to instantiate this one object, and invoke one method on it, and the object does the rest of the work. When other clients require the same functionality, they can reuse the new component.

You obtain a reference to a TransactionContext object with CreateObject. For example:

Set objTransactionContext = _

CreateObject("TxCtx.TransactionContext")

The TransactionContext object provides the following methods.

Method	Description
Abort	Aborts the work of all MTS objects participating in the current transaction. The transaction is completed on return from this method.
Commit	Attempts to commit the work of all MTS objects participating in the current transaction. If any of the MTS objects participating in the transaction have called SetAbort or DisableCommit, or if a system error has occurred, the transaction will be aborted. Otherwise, the transaction will be committed. In either case, the transaction is completed on return from this method.
CreateInstance	Instantiates another MTS object. If the component that provides the object is configured to support or require a transaction, then the new object runs under the transaction of the TransactionContextobject.
See Also

Transaction Context Objects, Base Clients, Transactions


Abort Method (Visual Basic)
Abort Method

Aborts the current transaction.

Applies To

TransactionContext Object

Syntax

transactioncontextobject.Abort

The transactioncontextobject placeholder represents an object variable that evaluates to a TransactionContext object.

Remarks

When a base client calls Abort, all objects that participated in the transaction are automatically deactivated. Any database updates made by those objects are rolled back. The transaction is completed on return from this method. If another call is made on the TransactionContext object after the TransactionContext object has returned from a call in which it called the Abort method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetAbort


Abort, Commit Methods Example (Visual Basic)
Abort, Commit Methods Example

Dim objTxCtx As TransactionContext

Dim objMyObject As MyCompany.MyObject

Dim userCanceled As Boolean

' Get TransactionContext.

Set objTxCtx = _

CreateObject("TxCtx.TransactionContext")

' Create an instance of some component.

Set objMyObject= _

objTxCtx.CreateInstance("MyCompany.MyObject")

' Do some work here.

' If something goes wrong, abort the transaction.

If userCanceled Then

objTxCtx.Abort

' Otherwise, commit it.

Else

objTxCtx.Commit

End If


Commit Method (Visual Basic)
Commit Method

Attempts to commit the current transaction.

Applies To

TransactionContext Object

Syntax

transactioncontextobject.Commit

The transactioncontextobject placeholder represents an object variable that evaluates to a TransactionContext object.

Remarks

Calling Commit doesn't guarantee that a transaction will be committed. If any MTS object that was part of the transaction has returned from a method after calling SetAbort, the transaction will be aborted. If any object that was part of the transaction has called DisableCommit and hasn't yet called EnableCommit or SetComplete, the transaction will also be aborted. Any error that causes Microsoft Distributed Transaction Coordinator to abort a transaction will also abort an MTS transaction.

When a base client calls Commit, regardless of whether the transaction commits or aborts, the transaction is completed on return from this method and all objects that participated in the transaction are automatically deactivated. If another call comes in after the TransactionContext object has returned from a call in which it called the Commit method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetComplete


CreateInstance Method, TransactionContext (Visual Basic)
CreateInstance Method

Instantiates an MTS object that will execute within the scope of the transaction that was initiated with the creation of the TransactionContext object.

Applies To

TransactionContext Object

Syntax

Set object = transactioncontextobject.CreateInstance(programmaticID)

Part

object
An object variable that evaluates to an MTS object.

transactioncontextobject
An object variable that represents the TransactionContext object from which to create the new object.

programmaticID
The programmatic Id of the new object's component.

Remarks

When a base client uses the TransactionContext object's CreateInstance method to instantiate an MTS object, the new object executes within the transaction context object's activity. If the transaction attribute of the new object's component is set to either Supports transactions or Requires a transaction, the new object also inherits the transaction initiated with the creation of the TransactionContext object. However, if the component that provides the new object has its transaction attribute set to Does not support transactions, the object neither inherits the transaction nor passes it on to objects it subsequently creates. If the component that provides the new object has its transaction attribute set to Requires a new transaction, the MTS run-time environment initiates a new transaction for the new object, and that transaction is the one that's inherited by objects it subsequently creates.

In this respect, using CreateInstance is comparable to using CoCreateInstance and specifying NULL for the controlling IUnknown interface (pUnkOuter).

Example

See Also

Transaction Context Objects, Base Clients, Transactions, CreateInstance


CreateInstance Method, TransactionContext Object Example (Visual Basic)
CreateInstance Method, TransactionContext Object Example

Dim objTxCtx As TransactionContext

Dim objMyObject As MyCompany.MyObject

' Get TransactionContext.

Set objTxCtx = _

CreateObject("TxCtx.TransactionContext")

' Create an instance of MyObject.

Set objMyObject= _

objTxCtx.CreateInstance("MyCompany.MyObject")


ITransactionContextEx Interface (Visual C++)
ITransactionContextEx Interface

The ITransactionContextEx interface is used by a base client to compose the work of one or more MTS objects into an atomic transaction and to commit or abort the transaction.

Remarks

The header file for the ITransactionContextEx interface is txctx.h. You must also link mtxguid.lib to your project to use this interface.

You can use a TransactionContextEx object to scope a transaction from a base client. You begin the transaction by instantiating a TransactionContextEx object, and you end the transaction by calling Commit or Abort on the object. The base client itself never executes within the transaction.

The TransactionContextEx component is a standard MTS component. The component's transaction attribute is set to Requires a new transaction, which means that a TransactionContextEx object is always the root of a transaction. When a base client instantiates an object by using the ITransactionContextEx::CreateInstance method, the new object and its descendants will participate in theTransactionContextEx object's transaction unless the new object's transaction attribute is set to Requires a new transaction or Does not support transactions.

You could easily write your own TransactionContextEx component. You would simply create a component that implements the methods Commit, Abort, and CreateInstance, and set the component's transaction attribute to Requires a new transaction. The three methods would do nothing more than call GetObjectContext and invoke their ObjectContext object's SetComplete, SetAbort, and CreateInstance methods, respectively.

Before you use TransactionContextEx to compose the work of existing components in a transaction, you should consider implementing a separate component that not only composes their work but encapsulates it into a reusable unit. This new component would not only serve the needs of the current base client, but other clients could also use it. In one approach, the base client instantiates a TransactionContextEx object, calls its CreateInstance method to instantiate other objects, calls various methods on those objects, and finally calls Commit or Abort on the TransactionContextEx object. In the other approach, you create a new component that requires a transaction. This new component instantiates the other objects using its ObjectContext object's CreateInstance method, calls the relevant methods on those other objects itself, and then calls SetComplete or SetAbort on its ObjectContext when it's done. Using this approach, the base client only needs to instantiate this one object, and invoke one method on it, and the object does the rest of the work. When other clients require the same functionality, they can reuse the new component.

You obtain a reference to the ITransactionContextEx interface by creating a TransactionContextEx object with a call to CoCreateInstance. For example:

CoCreateInstance(CLSID_TransactionContextEx, NULL, CLSCTX_INPROC,
IID_ITransactionContextEx, (void**)&m_pTransactionContext);

The ITransactionContextEx interface exposes the following methods.

Method	Description
Abort	Aborts the work of all MTS objects participating in the current transaction. The transaction is completed on return from this method.
Commit	Attempts to commit the work of all MTS objects participating in the current transaction. If any of the MTS objects participating in the transaction have called SetAbort or DisableCommit, or if a system error has occurred, the transaction will be aborted. Otherwise, the transaction will be committed. In either case, the transaction is completed on return from this method.
CreateInstance	Instantiates another MTS object. If the component that provides the object is configured to support or require a transaction, then the new object runs under the transaction of the TransactionContextExobject.
See Also

Transaction Context Objects, Base Clients, Transactions


ITransactionContextEx::Abort Method (Visual C++)
ITransactionContextEx::Abort Method

Aborts the current transaction.

Provided By

ITransactionContextEx Interface

HRESULT ITransactionContextEx::Abort ( );

Return Values

S_OK
The transaction was aborted.

E_FAIL
The TransactionContextEx object isn't running under a MTS process. This could happen if the TransactionContextEx component's Registry entry has been corrupted.

E_UNEXPECTED
An unexpected error occurred.

Remarks

When a base client calls Abort, all objects that participated in the transaction are automatically deactivated. Any database updates made by those objects are rolled back. The transaction is completed on return from this method. If another call is made on the TransactionContextEx object after the TransactionContextEx object has returned from a call in which it called the Abort method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetAbort


ITransactionContextEx::Abort, ITransactionContextEx::Commit Methods Example (Visual C++)
ITransactionContextEx::Abort, ITransactionContextEx::Commit Methods Example

#include <Txctx.h>

ITransactionContextEx* pTransactionContext = NULL;

IMyObject* pMyObject = NULL;

boolean bUserCanceled = FALSE;

HRESULT hr;

// Get TransactionContextEx.

hr = CoCreateInstance(CLSID_ITransactionContextEx,

NULL, CLSCTX_INPROC, IID_ITransactionContextEx,

(void**) &pTransactionContext);

// Create an instance of MyObject.

hr = pTransactionContext->CreateInstance

(CLSID_CMyObject, IID_IMyObject,

(void**) &pMyObject);

// Do some work here.

// If something goes wrong, abort the transaction.

if (bUserCanceled)

pTransactionContext->Abort();

// Otherwise, commit it.

else

pTransactionContext->Commit();


ITransactionContextEx::Commit Method (Visual C++)
ITransactionContextEx::Commit Method

Attempts to commit the current transaction.

Provided By

ITransactionContextEx Interface

HRESULT ITransactionContextEx::Commit ( );

Return Values

S_OK
The transaction was committed.

E_FAIL
The TransactionContextEx object isn't running under a MTS process. This could happen if the TransactionContextEx component's Registry entry has been corrupted.

E_UNEXPECTED
An unexpected error occurred.

CONTEXT_E_ABORTED
The transaction was aborted.

Remarks

Calling Commit doesn't guarantee that a transaction will be committed. If any MTS object that was part of the transaction has returned from a method after calling SetAbort, the transaction will be aborted. If any object that was part of the transaction has called DisableCommit and hasn't yet called EnableCommit or SetComplete, the transaction will also be aborted. Any error that causes Microsoft Distributed Transaction Coordinator to abort a transaction will also abort an MTS transaction.

When a base client calls Commit, regardless of whether the transaction commits or aborts, the transaction is completed on return from this method and all objects that participated in the transaction are automatically deactivated. If another call comes in after the TransactionContextEx object has returned from a call in which it called the Commit method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetComplete


ITransactionContextEx::CreateInstance Method (Visual C++)
ITransactionContextEx::CreateInstance Method

Instantiates an MTS object that will execute within the scope of the transaction that was initiated with the creation of the TransactionContextEx object.

Provided By

ITransactionContextEx Interface

HRESULT ITransactionContextEx::CreateInstance (

REFCLSID rclsid,

REFIID riid,

LPVOID FAR* ppvObj

);

Parameter

rclsid
[in] A reference to the CLSID of the type of object to instantiate.

riid
[in] A reference to the interface ID of the interface through which you want to communicate with the new object.

ppvObj
[out] A reference to a new object of the type specified by the rclsid argument, through the interface specified by the riid argument.

Return Values

S_OK
A reference to the object is returned in the ppvObj parameter.

REGDB_E_CLASSNOTREG
The component specified by rclsid is not registered as a COM component.

E_OUTOFMEMORY
There's not enough memory available to instantiate the object.

E_INVALIDARG
The argument passed in the ppvObj parameter is invalid.

E_UNEXPECTED
An unexpected error occurred.

Remarks

When a base client uses the ITransactionContextEx::CreateInstance method to instantiate an MTS object, the new object executes within the transaction context object's activity. If the transaction attribute of the new object's component is set to either Supports transactions or Requires a transaction, the new object also inherits the transaction initiated with the creation of the TransactionContextEx object. However, if the component that provides the new object has its transaction attribute set to Does not support transactions, the object neither inherits the transaction nor passes it on to objects it subsequently creates. If the component that provides the new object has its transaction attribute set to Requires a new transaction, the MTS run-time environment initiates a new transaction for the new object, and that transaction is the one that's inherited by objects it subsequently creates.

If the Microsoft Distributed Transaction Coordinator is not running and the object is transactional, the object is successfully created. However, method calls to that object will fail with CONTEXT_E_TMNOTAVAILABLE. Objects cannot recover from this condition and should be released.

MTS always uses standard marshaling. Even if a component exposes the IMarshal interface, its IMarshal methods will never be called by the MTS run-time environment.

Note   You can't create MTS objects as part of an aggregation. In this respect, using CreateInstance is comparable to using CoCreateInstance and specifying NULL for the controlling IUnknown interface (pUnkOuter).

Example

See Also

Transaction Context Objects, Base Clients, Transactions, CreateInstance


ITransactionContextEx::CreateInstance Method Example (Visual C++)
ITransactionContextEx::CreateInstance Method Example

#include <Txctx.h>

ITransactionContextEx* pTransactionContext = NULL;

IMyObject* pMyObject = NULL;

HRESULT hr;

// Get TransactionContextEx.

hr = CoCreateInstance(CLSID_ITransactionContextEx,

NULL, CLSCTX_INPROC, IID_ITransactionContextEx,

(void**) &pTransactionContext);

// Create an instance of MyObject.

hr = pTransactionContext->CreateInstance

(CLSID_CMyObject, IID_IMyObject,

(void**) &pMyObject);


ITransactionContextEx Interface (Visual J++)
ITransactionContextEx Interface

The ITransactionContextEx interface is used by a base client to compose the work of one or more MTS objects into an atomic transaction and to commit or abort the transaction.

Remarks

The ITransactionContextEx interface is declared in the package com.ms.mtx.

You can use a TransactionContextEx object to scope a transaction from a base client. You begin the transaction by instantiating a TransactionContextEx object, and you end the transaction by calling Commit or Abort on the object. The base client itself never executes within the transaction.

The TransactionContextEx component is a standard MTS component. The component's transaction attribute is set to Requires a new transaction, which means that a TransactionContextEx object is always the root of a transaction. When a base client instantiates an object by using the ITransactionContextEx.CreateInstance method, the new object and its descendants will participate in theTransactionContextEx object's transaction unless the new object's transaction attribute is set to Requires a new transaction or Does not support transactions.

You could easily write your own TransactionContextEx component. You would simply create a component that implements the methods Commit, Abort, and CreateInstance, and set the component's transaction attribute to Requires a new transaction. The three methods would do nothing more than call GetObjectContext and invoke their ObjectContext object's SetComplete, SetAbort, and CreateInstance methods, respectively.

Before you use TransactionContextEx to compose the work of existing components in a transaction, you should consider implementing a separate component that not only composes their work but encapsulates it into a reusable unit. This new component would not only serve the needs of the current base client, but other clients could also use it. In one approach, the base client instantiates a TransactionContextEx object, calls its CreateInstance method to instantiate other objects, calls various methods on those objects, and finally calls Commit or Abort on the TransactionContextEx object. In the other approach, you create a new component that requires a transaction. This new component instantiates the other objects using its ObjectContext object's CreateInstance method, calls the relevant methods on those other objects itself, and then calls SetComplete or SetAbort on its ObjectContext when it's done. Using this approach, the base client only needs to instantiate this one object, and invoke one method on it, and the object does the rest of the work. When other clients require the same functionality, they can reuse the new component.

You obtain a reference to the ITransactionContextEx interface by creating a TransactionContextEx object. For example:

new TransactionContextEx();

The ITransactionContextEx interface exposes the following methods.

Method	Description
Abort	Aborts the work of all MTS objects participating in the current transaction. The transaction is completed on return from this method.
Commit	Attempts to commit the work of all MTS objects participating in the current transaction. If any of the MTS objects participating in the transaction have called SetAbort or DisableCommit, or if a system error has occurred, the transaction will be aborted. Otherwise, the transaction will be committed. In either case, the transaction is completed on return from this method.
CreateInstance	Instantiates another MTS object. If the component that provides the object is configured to support or require a transaction, then the new object runs under the transaction of the TransactionContextExobject.
See Also

Transaction Context Objects, Base Clients, Transactions


ITransactionContextEx.Abort Method (Visual J++)
ITransactionContextEx.Abort Method

Aborts the current transaction.

Provided By

ITransactionContextEx Interface

void Abort ( );

Remarks

When a base client calls Abort, all objects that participated in the transaction are automatically deactivated. Any database updates made by those objects are rolled back. The transaction is completed on return from this method. If another call is made on the TransactionContextEx object after the TransactionContextEx object has returned from a call in which it called the Abort method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetAbort


ITransactionContext.Abort, ITransactionContext.Commit Methods Example (Visual J++)
ITransactionContext.Abort, ITransactionContext.Commit Methods Example

import com.ms.mtx.*;

ITransactionContextEx myTransactionContext = null;

IMyObject myObject = null;

boolean userCanceled = false;

// Get TransactionContextEx.

myTransactionContext = new TransactionContextEx();

// Create an instance of MyObject.

myObject = myTransactionContext.CreateInstance (CMyObject.clsid, IMyObject.iid);

// Do some work here.

// If something goes wrong, abort the transaction.

if (userCanceled)

myTransactionContext.Abort();

// Otherwise, commit it.

else

pTransactionContext.Commit();


ITransactionContextEx.Commit Method (Visual J++)
ITransactionContextEx.Commit Method

Attempts to commit the current transaction.

Provided By

ITransactionContextEx Interface

void Commit ( );

Remarks

Calling Commit doesn't guarantee that a transaction will be committed. If any MTS object that was part of the transaction has returned from a method after calling SetAbort, the transaction will be aborted. If any object that was part of the transaction has called DisableCommit and hasn't yet called EnableCommit or SetComplete, the transaction will also be aborted. Any error that causes Microsoft Distributed Transaction Coordinator to abort a transaction will also abort an MTS transaction.

When a base client calls Commit, regardless of whether the transaction commits or aborts, the transaction is completed on return from this method and all objects that participated in the transaction are automatically deactivated. If another call comes in after the TransactionContextEx object has returned from a call in which it called the Commit method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetComplete


ITransactionContextEx.CreateInstance Method (Visual J++)
ITransactionContextEx.CreateInstance Method

Instantiates an MTS object that will execute within the scope of the transaction that was initiated with the creation of the TransactionContextEx object.

Provided By

ITransactionContextEx Interface

IUnknown CreateInstance (

_Guid clsid,

_Guid  iid,

);

Parameter

clsid
[in] A reference to the CLSID of the type of object to instantiate.

iid
[in] Any interface that's implemented by the object you want to instantiate.

Return Value

A reference to the IUnknown interface on a new instance of the MTS component specified in the clsid parameter.

Remarks

When a base client uses the ITransactionContextEx.CreateInstance method to instantiate an MTS object, the new object executes within the transaction context object's activity. If the transaction attribute of the new object's component is set to either Supports transactions or Requires a transaction, the new object also inherits the transaction initiated with the creation of the TransactionContextEx object. However, if the component that provides the new object has its transaction attribute set to Does not support transactions, the object neither inherits the transaction nor passes it on to objects it subsequently creates. If the component that provides the new object has its transaction attribute set to Requires a new transaction, the MTS run-time environment initiates a new transaction for the new object, and that transaction is the one that's inherited by objects it subsequently creates.

CreateInstance always returns the IUnknown interface on the newly instantiated object. You should immediately cast the returned value to the interface with which you want to communicate with the new object. The interface ID you pass in the iid parameter doesn't have to be the same interface to which you cast the returned value, but it must be an interface that's implemented by the object you want to instantiate.

MTS always uses standard marshaling. Even if a component exposes the IMarshal interface, its IMarshal methods will never be called by the MTS run-time environment.

Note   You can't create MTS objects as part of an aggregation.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, CreateInstance


ITransactionContextEx.CreateInstance Method Example (Visual J++)
ITransactionContext.CreateInstance Method Example

import com.ms.mtx.*;

ITransactionContextEx myTransactionContext = null;

IMyObject myObject = null;

// Get TransactionContextEx.

myTransactionContext = new TransactionContextEx();

// Create an instance of MyObject.

myObject = (IMyObject)

myTransactionContext.CreateInstance

(CMyObject.clsid, IMyObject.iid);


SecurityProperty Object (Visual Basic)
SecurityProperty Object

The SecurityProperty object is used to determine the current object's caller or creator.

Remarks

To use the SecurityProperty object, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

You obtain a reference to an object's SecurityProperty object by calling Security on the object's ObjectContext. For example:

Set secObject = ctxObject.Security

The SecurityProperty object provides the following methods.

Method	Description
GetDirectCallerName	Retrieves the user name associated with the external process that called the currently executing method.
GetDirectCreatorName	Retrieves the user name associated with the external process that directly created the current object.
GetOriginalCallerName	Retrieves the user name associated with the base process that initiated the call sequence from which the current method was called.
GetOriginalCreatorName	Retrieves the user name associated with the base process that initiated the activity in which the current object is executing.
See Also

Programmatic Security, Advanced Security Methods, ObjectContext Object


GetDirectCallerName Method (Visual Basic)
GetDirectCallerName Method

Retrieves the user name associated with the external process that called the currently executing method.

Applies To

SecurityProperty Object

Syntax

username = securityproperty.GetDirectCallerName( )

Part

username
The user name associated with the process from which the current method was invoked.

securityproperty
An object variable that evaluates to a SecurityProperty object.

Remarks

You use the GetDirectCallerName method to determine the user name associated with the process that called the object's currently executing method. The following scenarios illustrate the functionality of the GetDirectCallerName method.

A base process running on server A, as user A, calls into object X on server B, running as user B. Then object X calls into object Y, running on server C. If object Y calls GetDirectCallerName, the name of user B is returned.

Security can only be enforced across process boundaries. This means that the name returned by GetDirectCallerName is the name associated with the process that called into the process in which the current object is running, not necessarily the immediate caller into the object itself. If an object calls into another object within the same process, when the second object calls GetDirectCallerName, it will get the name of the most immediate caller outside its own process boundary, not the name of the object that directly called into it.

A base process, running on server A as user A, calls into object X on server B, running as user B. Then object X calls into object Y, running in the same process as object X, also on server B. When object Y calls GetDirectCallerName, the name of user A is returned , not the name of user B.

Example

See Also

Programmatic Security, Advanced Security Methods, ObjectContext Object


GetDirectCallerName Method Example (Visual Basic)
GetDirectCallerName Method Example

Public Function ComponentDirectCaller() As String

    Dim objCtx As ObjectContext

    Set objCtx = GetObjectContext()

    ComponentDirectCaller = _

        objCtx.Security.GetDirectCallerName()

End Function


GetDirectCreatorName Method (Visual Basic)
GetDirectCreatorName Method

Retrieves the user name associated with the current object's immediate (out-of-process) creator.

Applies To

SecurityProperty Object

Syntax

username = securityproperty.GetDirectCreatorName( )

Part

username
The user name associated with the process that directly created the current object.

securityproperty
An object variable that evaluates to a SecurityProperty object.

Remarks

You use the GetDirectCreatorName method to determine the user name associated with the process that created the current object. The following scenarios illustrate the functionality of the GetDirectCreatorName method.

A base process running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running on server C. If object Y calls GetDirectCreatorName, the name of user B is returned.

Security can only be enforced across process boundaries. This means that if an object creates another object within the same process, when the second object calls GetDirectCreatorName, it will get the name of the most immediate creator outside its own process boundary, not the user name associated with the object that actually created it.

A base client running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running in the same process as object X, also on server B. When object Y calls GetDirectCreatorName, the name of user A is returned, not the name of user B.

Example

See Also

Programmatic Security, Advanced Security Methods, ObjectContext Object


GetDirectCreatorName Method Example (Visual Basic)
GetDirectCreatorName Method Example

Public Function ComponentDirectCreator() As String

    Dim objCtx As ObjectContext

    Set objCtx = GetObjectContext()

    ComponentDirectCreator = _

        objCtx.Security.GetDirectCreatorName()

End Function


GetOriginalCallerName Method (Visual Basic)
GetOriginalCallerName Method

Retrieves the user name associated with the base process that initiated the sequence of calls from which the call into the current object originated.

Applies To

SecurityProperty Object

Syntax

username = securityproperty.GetOriginalCallerName( )

Part

username
The user name associated with the base process that initiated the call sequence from which the current method was called.

securityproperty
An object variable that evaluates to a SecurityProperty object.

Remarks

You use the GetOriginalCallerName method to determine the user name associated with the original process that initiated the call sequence from which the current method was called. The following scenario illustrates the functionality of the GetOriginalCallerName method.

Base process 1, running on server A as user A, creates object X on server B, running as user B. Then base process 1 passes its reference on object X to base process 2, running on server D as user D. Base process 2 uses that reference to call into object X. object X then calls into object Y, running on server C. If object Y then calls GetOriginalCallerName, the name of user D is returned.

Note   Usually, an object's original caller is the same process as its original creator. The only situation in which the original caller and the original creator would be different is one in which the original creator passes a reference to another process, and the other process initiates the call sequence (as in the preceding example).

Note   The path to the original caller is broken if any object along the chain was created by some other means than IObjectContext::CreateInstance or ITransactionContext::CreateInstance. For example, if base process 1 uses CoCreateInstance to create X, when Y calls GetOriginalCallerName, the name it gets back will be the name of user B, not user D. This is because the call sequence is traced back through the objects' context and MTS can only create a context for an object that's created with either IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

Example

See Also

Programmatic Security, Advanced Security Methods, ObjectContext Object


GetOriginalCallerName Method Example (Visual Basic)
GetOriginalCallerName Method Example

Public Function ComponentOriginalCaller() As String

    Dim objCtx As ObjectContext

    Set objCtx = GetObjectContext()

    ComponentOriginalCaller = _

        objCtx.Security.GetOriginalCallerName()

End Function


GetOriginalCreatorName Method (Visual Basic)
GetOriginalCreatorName Method

Retrieves the user name associated with the original base process that initiated the activity in which the current object is executing.

Applies To

SecurityProperty Object

Syntax

username = securityproperty.GetOriginalCreatorName( )

Part

username
The user name associated with the base process that initiated the activity in which the current object is executing.

securityproperty
An object variable that evaluates to a SecurityProperty object.

Remarks

You use the GetOriginalCreatorName method to determine the user name associated with the process that initiated the activity in which the current object is executing. The following scenario illustrates the functionality of the GetOriginalCreatorName method.

A base process running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running on server C. If object Y calls GetOriginalCreatorName, the name of user A is returned.

Note   The path to the original creator is broken if an object is created by some other means than IObjectContext::CreateInstance or ITransactionContext::CreateInstance. For example, if the base process on server A uses CoCreateInstance to create X, when Y calls GetOriginalCreatorName, the name it gets back will be the name of user B, not user A. This is because the creation sequence is traced back through the objects' context and MTS can only create a context for an object that's created with either IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

Example

See Also

Programmatic Security, Advanced Security Methods, ObjectContext Object


GetOriginalCreatorName Method Example (Visual Basic)
GetOriginalCreatorName Method Example

Public Function ComponentOriginalCreator() As String

    Dim objCtx As ObjectContext

    Set objCtx = GetObjectContext()

    ComponentOriginalCreator = _

        objCtx.Security.GetOriginalCreatorName()

End Function


ISecurityProperty Interface (Visual C++)
ISecurityProperty Interface

The ISecurityProperty interface is used to determine the security ID of the current object's caller or creator.

Remarks

The header file for the ISecurityProperty interface is mtx.h. You must also link mtxguid.lib to your project to use this interface.

You obtain a reference to an object's ISecurityProperty interface by calling QueryInterface on the object's ObjectContext. For example:

m_pIObjectContext->QueryInterface (IID_ISecurityProperty, (void**)&m_pISecurityProperty);

The ISecurityProperty interface provides the following methods.

Method	Description
GetDirectCallerSID	Retrieves the security ID of the external process that called the currently executing method.
GetDirectCreatorSID	Retrieves the security ID of the external process that directly created the current object.
GetOriginalCallerSID	Retrieves the security ID of the base process that initiated the call sequence from which the current method was called.
GetOriginalCreatorSID	Retrieves the security ID of the base process that initiated the activity in which the current object is executing.
ReleaseSID	Releases the security ID returned by one of the other ISecurityProperty methods.
See Also

Programmatic Security, Advanced Security Methods, IObjectContext Interface


ISecurityProperty::GetDirectCallerSID Method (Visual C++)
ISecurityProperty::GetDirectCallerSID Method

Retrieves the security ID of the external process that called the currently executing method.

Provided By

ISecurityProperty Interface

HRESULT ISecurityProperty::GetDirectCallerSID (

PSID* ppSid

);

Parameters

ppSid
[out] A reference to the security ID of the process from which the current method was invoked.

Return Values

S_OK
The security ID of the process that called the current method is returned in the parameter ppSid.

E_INVALIDARG
The argument passed in the ppSid parameter is a NULL pointer.

E_UNEXPECTED
An unexpected error occurred.

Remarks

You use the GetDirectCallerSID method to determine the security ID of the process that called the object's currently executing method. The following scenarios illustrate the functionality of the GetDirectCallerSID method.

A base process running on server A, as user A, calls into object X on server B, running as user B. Then object X calls into object Y, running on server C. If object Y calls GetDirectCallerSID, the the security ID of user B is returned.

Security can only be enforced across process boundaries. This means that the the security ID returned by GetDirectCallerSID is the the security ID associated with the process that called into the process in which the current object is running, not necessarily the immediate caller into the object itself. If an object calls into another object within the same process, when the second object calls GetDirectCallerSID, it will get the the security ID of the most immediate caller outside its own process boundary, not the the security ID of the object that directly called into it.

A base process, running on server A as user A, calls into object X on server B, running as user B. Then object X calls into object Y, running in the same process as object X, also on server B. When object Y calls GetDirectCallerSID, the the security ID of user A is returned , not the the security ID of user B.

You must call ReleaseSID on a security ID when you finish using it.

Example

See Also

Programmatic Security, Advanced Security Methods, IObjectContext Interface


ISecurityProperty::GetDirectCallerSID Method Example (Visual C++)
GetDirectCallerSID Method Example

#include <mtx.h>

IObjectContext* pIObjectContext = NULL;

ISecurityProperty* pISecurityProperty = NULL;

PSID pSid = NULL;

HRESULT hr;

// Get a reference to the ISecurityProperty interface.

pIObjectContext->QueryInterface(IID_ISecurityProperty,

(void**)&pISecurityProperty);

// Obtain the caller's security ID.

hr = pISecurityProperty->GetDirectCallerSID(&pSid)

//	Do some security checking here.

// Release the security ID.

pISecurityProperty->ReleaseSID(pSid);


ISecurityProperty::GetDirectCreatorSID Method (Visual C++)
ISecurityProperty::GetDirectCreatorSID Method

Retrieves the security ID of the current object's immediate (out-of-process) creator.

Provided By

ISecurityProperty Interface

HRESULT ISecurityProperty::GetDirectCreatorSID (

PSID* ppSid

);

Parameters

ppSid
[out] A reference to the security ID of the process that directly created the current object.

Return Values

S_OK
The security ID of the process that directly created the current object is returned in the parameter ppSid.

E_INVALIDARG
The argument passed in the ppSid parameter is a NULL pointer.

E_FAIL
An unexpected error occurred.

Remarks

You use the GetDirectCreatorSID method to determine the security ID of the process that created the current object. The following scenarios illustrate the functionality of the GetDirectCreatorSID method.

A base process running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running on server C. If object Y calls GetDirectCreatorSID, the the security ID of user B is returned.

Security can only be enforced across process boundaries. This means that if an object creates another object within the same process, when the second object calls GetDirectCreatorSID, it will get the the security ID of the most immediate creator outside its own process boundary, not the security ID of the object that actually created it.

A base client running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running in the same process as object X, also on server B. When object Y calls GetDirectCreatorSID, the the security ID of user A is returned, not the the security ID of user B.

You must call ReleaseSID on a security ID when you finish using it.

Example

See Also

Programmatic Security, Advanced Security Methods, IObjectContext Interface


ISecurityProperty::GetDirectCreatorSID Method Example (Visual C++)
GetDirectCreatorSID Method Example

#include <mtx.h>

IObjectContext* pIObjectContext = NULL;

ISecurityProperty* pISecurityProperty = NULL;

PSID pSid = NULL;

HRESULT hr;

// Get a reference to the ISecurityProperty interface.

pIObjectContext->QueryInterface(IID_ISecurityProperty,

(void**)&pISecurityProperty);

// Obtain the creator's security ID.

hr = pISecurityProperty->GetDirectCreatorSID(&pSid)

// Do some security checking here.

// Release the security ID.

pISecurityProperty->ReleaseSID(pSid);


ISecurityProperty::GetOriginalCallerSID Method (Visual C++)
ISecurityProperty::GetOriginalCallerSID Method

Retrieves the security ID of the base process that initiated the sequence of calls from which the call into the current object originated.

Provided By

ISecurityProperty Interface

HRESULT ISecurityProperty::GetOriginalCallerSID (

PSID* ppSid

);

Parameters

ppSid
[out] A reference to the security ID of the base process that initiated the call sequence from which the current method was called.

Return Values

S_OK
The security ID of the base process that originated the call into the current object is returned in the parameter ppSid.

E_INVALIDARG
The argument passed in the ppSid parameter is a NULL pointer.

E_FAIL
An unexpected error occurred.

Remarks

You use the GetOriginalCallerSID method to determine the security ID of the original process that initiated the call sequence from which the current method was called. The following scenario illustrates the functionality of the GetOriginalCallerSID method.

Base process 1, running on server A as user A, creates object X on server B, running as user B. Then base process 1 passes its reference on object X to base process 2, running on server D as user D. Base process 2 uses that reference to call into object X. object X then calls into object Y, running on server C. If object Y then calls GetOriginalCallerSID, the the security ID of user D is returned.

Note   Usually, an object's original caller is the same process as its original creator. The only situation in which the original caller and the original creator would be different is one in which the original creator passes a reference to another process, and the other process initiates the call sequence (as in the preceding example).

Note   The path to the original caller is broken if any object along the chain was created by some other means than IObjectContext::CreateInstance or ITransactionContext::CreateInstance. For example, if base process 1 uses CoCreateInstance to create X, when Y calls GetOriginalCallerSID, the the security ID it gets back will be the the security ID of user B, not user D. This is because the call sequence is traced back through the objects' context and MTS can only create a context for an object that's created with either IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

You must call ReleaseSID on a security ID when you finish using it.

Example

See Also

Programmatic Security, Advanced Security Methods, IObjectContext Interface


ISecurityProperty::GetOriginalCallerSID Method Example (Visual C++)
GetOriginalCallerSID Method Example

#include <mtx.h>

IObjectContext* pIObjectContext = NULL;

ISecurityProperty* pISecurityProperty = NULL;

PSID pSid = NULL;

HRESULT hr;

// Get a reference to the ISecurityProperty interface.

pIObjectContext->QueryInterface(IID_ISecurityProperty,

(void**)&pISecurityProperty);

// Obtain the original caller's security ID.

hr = pISecurityProp->GetOriginalCallerSID(&pSid)

// Do some security checking here.

// Release the security ID.

pISecurityProperty->ReleaseSID(pSid);


ISecurityProperty::GetOriginalCreatorSID Method (Visual C++)
ISecurityProperty::GetOriginalCreatorSID Method

Retrieves the security ID of the original base process that initiated the activity in which the current object is executing.

Provided By

ISecurityProperty Interface

HRESULT ISecurityProperty::GetOriginalCreatorSID (

PSID* ppSid

);

Parameters

ppSid
[out] A reference to the security ID of the base process that initiated the activity in which the current object is executing.

Return Values

S_OK
The security ID of the original creator is returned in the parameter ppSid.

E_INVALIDARG
The argument passed in the ppSid parameter is a NULL pointer.

E_FAIL
An unexpected error occurred.

Remarks

You use the GetOriginalCreatorSID method to determine the security ID of the process that initiated the activity in which the current object is executing. The following scenario illustrates the functionality of the GetOriginalCreatorSID method.

A base process running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running on server C. If object Y calls GetOriginalCreatorSID, the the security ID of user A is returned.

Note   The path to the original creator is broken if an object is created by some other means than IObjectContext::CreateInstance or ITransactionContext::CreateInstance. For example, if the base process on server A uses CoCreateInstance to create X, when Y calls GetOriginalCreatorSID, the the security ID it gets back will be the the security ID of user B, not user A. This is because the creation sequence is traced back through the objects' context and MTS can only create a context for an object that's created with either IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

You must call ReleaseSID on a security ID when you finish using it.

Example

See Also

Programmatic Security, Advanced Security Methods, IObjectContext Interface


ISecurityProperty::GetOriginalCreatorSID, ISecurityProperty::ReleaseSID Methods Example (Visual C++)
GetOriginalCreatorSID, ReleaseSID Methods Example

#include <mtx.h>

IObjectContext* pIObjectContext = NULL;

ISecurityProperty* pISecurityProperty = NULL;

PSID pSid = NULL;

HRESULT hr;

// Get a reference to the ISecurityProperty interface.

pIObjectContext->QueryInterface(IID_ISecurityProperty,

(void**)&pISecurityProperty);

// Obtain the original creator's security ID.

hr = pISecurityProp->GetOriginalCreatorSID(&pSid)

// Do some security checking here.

// Release the security ID.

pISecurityProperty->ReleaseSID(pSid);


ISecurityProperty::ReleaseSID Method (Visual C++)
ISecurityProperty::ReleaseSID Method

Releases a security ID that was obtained from the GetDirectCallerSID, GetDirectCreatorSID, GetOriginalCallerSID, or GetOriginalCreatorSID method.

Provided By

ISecurityProperty Interface

HRESULT ISecurityProperty::ReleaseSID (

PSID pSid

);

Parameters

pSid
[in] A reference to a security ID that was obtained by invoking one of the ISecurityProperty methods.

Return Values

S_OK
The security ID, passed in the pSid parameter, was released.

E_INVALIDARG
The argument passed in the pSid parameter is not a reference to a security ID.

Remarks

You should always invoke the ReleaseSID method to release any security ID pointers returned by the GetDirectCallerSID, GetDirectCreatorSID, GetOriginalCallerSID, and GetOriginalCreatorSID methods of the ISecurityProperty interface.

See Also

Programmatic Security, Advanced Security Methods, IObjectContext Interface


Context.getDirectCallerName Method (Visual J++)
getDirectCallerName Method

Retrieves the user name associated with the external process that called the currently executing method.

String getDirectCallerName ( );

Provided By

Context class

Return Values

User name associated with the process from which the current method was invoked.

Remarks

You use the getDirectCallerName method to determine the user name associated with the process that called the object's currently executing method. The following scenarios illustrate the functionality of the getDirectCallerName method.

A base process running on server A, as user A, calls into object X on server B, running as user B. Then object X calls into object Y, running on server C. If object Y calls getDirectCaller, the name of user B is returned.

Security can only be enforced across process boundaries. This means that the name returned by getDirectCallerName is the name associated with the process that called into the process in which the current object is running, not necessarily the immediate caller into the object itself. If an object calls into another object within the same process, when the second object calls getDirectCallerName, it will get the name of the most immediate caller outside its own process boundary, not the name of the object that directly called into it.

A base process, running on server A as user A, calls into object X on server B, running as user B. Then object X calls into object Y, running in the same process as object X, also on server B. When object Y calls getDirectCallerName, the name of user A is returned , not the name of user B.

See Also

Programmatic Security, Advanced Security Methods, Context class


Context.getDirectCreatorName Method (Visual J++)
getDirectCreatorName Method

Retrieves the user name associated with the current object's immediate (out-of-process) creator.

Provided By

Context class

String getDirectCreatorName ( );

Return Values

User name associated with the process that directly created the current object.

Remarks

You use the getDirectCreatorName method to determine the  the process that created the current object. The following scenarios illustrate the functionality of the getDirectCreatorName method.

A base process running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running on server C. If object Y calls getDirectCreatorName, the name of user B is returned.

Security can only be enforced across process boundaries. This means that if an object creates another object within the same process, when the second object calls getDirectCreatorName, it will get the  of the most immediate creator outside its own process boundary, not the user name associated with the object that actually created it.

A base client running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running in the same process as object X, also on server B. When object Y calls getDirectCreatorName, the name of user A is returned, not the name of user B.

See Also

Programmatic Security, Advanced Security Methods, Context class


Context.getOriginalCallerName Method (Visual J++)
getOriginalCallerName Method

Retrieves the user name associated with the base process that initiated the sequence of calls from which the call into the current object originated.

Provided By

Context class

String getOriginalCallerName ( );

Return Values

User name associated with the the base process that initiated the call sequence from which the current method was called.

Remarks

You use the getOriginalCallerName method to determine the user name associated with the original process that initiated the call sequence from which the current method was called. The following scenario illustrates the functionality of the getOriginalCallerName method.

Base process 1, running on server A as user A, creates object X on server B, running as user B. Then base process 1 passes its reference on object X to base process 2, running on server D as user D. Base process 2 uses that reference to call into object X. object X then calls into object Y, running on server C. If object Y then calls getOriginalCallerName, the name of user D is returned.

Note   Usually, an object's original caller is the same process as its original creator. The only situation in which the original caller and the original creator would be different is one in which the original creator passes a reference to another process, and the other process initiates the call sequence (as in the preceding example).

Note   The path to the original caller is broken if any object along the chain was created by some other means than IObjectContext::CreateInstance or ITransactionContext::CreateInstance. For example, if base process 1 uses CoCreateInstance to create X, when Y calls getOriginalCallerName, the name it gets back will be the name of user B, not user D. This is because the call sequence is traced back through the objects' context and MTS can only create a context for an object that's created with either IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

See Also

Programmatic Security, Advanced Security Methods, Context class


Context.getOriginalCreatorNameMethod (Visual J++)
getOriginalCreatorName Method

Retrieves the user name associated with the original base process that initiated the activity in which the current object is executing.

Provided By

Context class

String getOriginalCreatorName ( );

Return Values

User name associated with the the base process that initiated the activity in which the current object is executing.

Remarks

You use the getOriginalCreatorName method to determine the  the process that initiated the activity in which the current object is executing. The following scenario illustrates the functionality of the getOriginalCreatorName method.

A base process running on server A, as user A, creates object X on server B, running as user B. Then object X creates object Y, running on server C. If object Y calls getOriginalCreatorName, the name of user A is returned.

Note   The path to the original creator is broken if an object is created by some other means than IObjectContext::CreateInstance or ITransactionContext::CreateInstance. For example, if the base process on server A uses CoCreateInstance to create X, when Y calls getOriginalCreatorName, the name it gets back will be the name of user B, not user A. This is because the creation sequence is traced back through the objects' context and MTS can only create a context for an object that's created with either IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

See Also

Programmatic Security, Advanced Security Methods, Context class


MTS Error Codes

The following errors can be returned by Microsoft Transaction Server (MTS) objects.

S_OK
The call succeeded.

E_INVALIDARG
One or more of the arguments passed in is invalid.

E_UNEXPECTED
An unexpected error occurred.

CONTEXT_E_NOCONTEXT
The current object doesn't have a context associated with it. This is probably either because its component hasn't been installed in a package or it wasn't created with one of the MTS CreateInstance methods.

CONTEXT_E_ROLENOTFOUND
The role specified in the szRole parameter in the IObjectContext::IsCallerInRole method does not exist.

E_OUTOFMEMORY
There's not enough memory available to instantiate the object. This error code can be returned by IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

REGDB_E_CLASSNOTREG
The specified component is not registered as a COM component. This error code can be returned by IObjectContext::CreateInstance or ITransactionContext::CreateInstance.

DISP_E_ARRAYISLOCKED
One or more of the arguments passed in contains an array that is locked. This error code can be returned by the ISharedProperty::put_Value method.

DISP_E_BADVARTYPE
One or more of the arguments passed in isn't a valid VARIANT type. This error code can be returned by the ISharedProperty::put_Value method.


MTS Supported Variant Types

The following Automation types are supported by Microsoft Transaction Server.

VT_BOOL	VT_LPSTR
VT_BSTR	VT_LPWSTR
VT_CARRAY	VT_NULL
VT_CLSID	VT_PTR
VT_CY	VT_R4
VT_DATE	VT_R8
VT_DECIMAL	VT_SAFEARRAY
VT_DISPATCH	VT_UINT
VT_EMPTY	VT_UI1
VT_ERROR	VT_UI2
VT_HRESULT	VT_UI4
VT_INT	VT_UI8
VT_I1	VT_UNKNOWN
VT_I2	VT_USERDEFINED
VT_I4	VT_VARIANT
VT_I8	VT_VOID
The following types are not supported and will cause the server process to terminate with an error.

VT_FILETIME	VT_BLOB
VT_STREAM	VT_STORAGE
VT_STREAMED_OBJECT	VT_STORED_OBJECT
VT_BLOB_OBJECT	VT_CF


MTS Administrative Reference

The Microsoft Transaction Server (MTS) Administrative reference provides object and method information for Microsoftｮ Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript) programmers, and interface and function information for Microsoft Visual C++ｮ programmers. In addition, this technical reference provides a detailed description of the collections used by the administration objects.

This section contains the following sections:

Using MTS Administration Objects

Using MTS Collection Types

Automating MTS Administration With Visual Basic

MTS Administration Object Methods

Automating MTS Administration With Visual C++

See Also

Automating MTS Administration


Automating MTS Administration With Visual Basic

This reference topic provides guidance for Microsoftｮ Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript) programmers who want to use the administration objects to automate tasks that an administrator performs using the Microsoft Transaction Server (MTS) Explorer. The MTS Visual Basic reference contains the following topics:

MTS Visual Basic Error Codes

MTS Administration Object Methods

See Also

Automating MTS Administration


MTS Administration Objects
Using MTS Administration Objects

Use the MTS administration objects to automate administration for MTS packages.

This section describes how the following administration objects are used:

MTS Catalog Object

MTS CatalogObject Object

MTS CatalogCollection Object

MTS PackageUtil Object

MTS ComponentUtil Object

MTS RemoteComponentUtil Object

MTS RoleAssociationUtil Object


MTS Catalog Object

The Catalog object enables you to connect to an MTS catalog and access collections. This general administration object supports the following methods.

Method	Description
GetCollection	Gets a collection on the catalog without reading any objects from the catalog.
Connect	Connects to a remote catalog and returns a root collection.
MajorVersion	Returns the major version number of the catalog.
MinorVersion	Returns the minor version number of the catalog.
See Also

MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object


MTS CatalogObject Object

The CatalogObject object allows you to get and set object properties. This general administration interface supports the following methods.

Method	Description
Value	Gets and sets a property value
Key	Gets the value of the key property
Name	Gets the name of the object
IsPropertyReadOnly	True if the property cannot be set
IsPropertyWriteOnly	True if the property only supports set
Valid	True if all properties were successfully read from the catalog data store
See Also

MTS Catalog Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object


MTS CatalogCollection Object

Use the CatalogCollection object to enumerate, add, delete, and modify catalog objects and to access related collections This general administration interface supports the following methods.

Method	Description
Item	Returns an object by index. The index is zero-based.
Count	Returns number of objects in the collection.
Remove	Removes an item according to its index position.
Add	Adds an object to the collection.
Populate	Reads all the collection objects from the catalog data store.
SaveChanges	Saves changes made to the collection into the catalog data store.
GetCollection	Gets a collection related to a specific object.
Name	Gets the name of a collection.
AddEnabled	Returns true if the Add method is enabled.
RemoveEnabled	Returns true if the Remove method is enabled.
GetUtilInterface	Gets the utility interface for the collection.
PopulateByKey	Reads the selected collection objects from the catalog data store.
DataStoreMajorVersion	Returns the major version number of the catalog data store.
DataStoreMinorVersion	Returns the minor version number of the catalog data store.
See Also

Add Method (CatalogCollection), Remove Method (CatalogCollection), MTS Catalog Object, MTS CatalogObject Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object


MTS PackageUtil Object

The PackageUtil object enables installing and exporting a package. Instantiate this object by calling GetUtilInterface on a Packages collection.

This utility administration interface supports the following methods:

Method	Description
InstallPackage	Installs a pre-built package.
ExportPackage	Exports a package.
ShutdownPackage	Shuts down a package, thereby terminating that server process.
See Also

MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object


MTS ComponentUtil Object

Call the ComponentUtil object to install a component in a specific collection and import components registered as in-process servers. Create this object by calling GetUtilInterface on a ComponentsInPackage collection. This utility administration interface supports the following methods.

Method	Description
InstallComponent	Installs a component from a DLL.
ImportComponent	Imports a component that is already registered as an in-process server. Supply the CLSID of the component.
ImportComponentByName	Imports a component that is already registered as an in-process server. Supply the ProgID of the component.
GetCLSIDS	Returns an array of installable CLSIDs in the DLL/type library. Note that changes are not made to the data store.
See Also

MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object


MTS RemoteComponentUtil Object

Using the RemoteComponentUtil object, you can program your application to pull remote components from a package on a remote server. Instantiate this object by calling GetUtilInterface on a RemoteComponents collection. This utility administration interface supports the following methods.

Method	Description
InstallRemoteComponent	Pulls remote components from a package on a remote server. Supply the package ID and CLSID.
InstallRemoteComponentByName	Pulls remote components from a package on a remote server. Supply the package name and ProgID.
See Also

GetUtilInterface Method (CatalogCollection), MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RoleAssociationUtil Object


MTS RoleAssociationUtil Object

Call methods on the RoleAssociationUtil object to associate roles with a component or interface. Create this object by calling the GetUtilInterface method on a RolesForPackageComponent or RolesForPackageComponentInterface collection. This utility administration interface supports the following methods.

Method	Description
AssociateRole	Associates the role by role ID with the component or interface.
AssociateRoleByName	Associates the role by role name with the component or interface.
See Also

GetUtilInterface Method (CatalogCollection), MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object


Using MTS Collections
Using MTS Collection Types

This topic describes the collections and collection properties supported by the MTS catalog. Additional collections and properties may be added in future versions. Use the DataStoreMajorVersion and DataStoreMinorVersion properties of a collection to distinguish between catalog versions.

The MTS catalog data store supports the following collection types:

MTS LocalComputer Collection

MTS ComputerList Collection

MTS Packages Collection

MTS ComponentsInPackage Collection

MTS RemoteComponents Collection

MTS InterfacesForComponent and InterfacesForRemoteComponent Collections

MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections

MTS MethodsForInterface Collection

MTS RolesInPackage Collection

MTS UsersInRole Collection

MTS ErrorInfo Collection

MTS PropertyInfo Collection

MTS RelatedCollectionInfo Collection


MTS LocalComputer Collection

The LocalComputer contains a single object that corresponds to the computer whose catalog that you are accessing. If you call the Connect method on the Catalog object, the LocalComputer collection contains information about the computer whose catalog you are accessing. This collection does not support the Add, Remove or GetUtilInterface methods.

The following table provides a list of the properties supported by the LocalComputer collection.

Property	Description
Name	"My Computer". Data Type: String Default value: N/A Access: Read only.
Description	Description of the computer. Data Type: String Default value: Empty string Access: Read/write
Transaction Timeout	The transaction timeout setting in seconds. Data Type: Integer Default value: 60 Access: Read/write
RemoteComponent InstallPath	The path in which remote component files will be installed when remote components are configured Data Type: String Default value: the subdirectory "Remote" in the MTS install path  Access: Read/write
PackageInstall Path	The default path in which component files will be installed when pre-built packages are installed. Data Type: String Default value: the subdirectory "Packages" in the MTS install path  Access: Read/write
ResourcePooling Enabled	"Y" enables resource pooling. "N" disables resource pooling. Note that resource pooling is currently only supported by the ODBC resource dispenser.  Data Type: String Default value: "Y"  Access: Read/write
ReplicationShare	When replicating the MTS catalog, the name of a share that the target system should use to access installed packages.  Data Type: String Default value: Empty string Access: Read/write
RemoteServer Name	The computer name to be generated when you use the MTS Explorer to create a client executable. If this string is blank or empty, the physical computer name of the exporting computer is used. If you put the name of the remote server as the string, the application executable generated by the MTS Explorer points to that remote server name. Data Type: String Default value: Empty string Access: Read/write
See Also

RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS ComputerList Collection

The ComputerList collection provides access to the list of computers shown in the MTS Explorer Computers folder. This collection supports the  Add and Remove methods. This collection does not support the GetUtilInterface method.

The following table provides a list of the properties supported by the ComputerList collection.

Property	Description
Name	The name of the computer. Data Type: String Default value: "NewComputer" Access: Read/Write while using the Add method. After adding, read-only.
See Also

RelatedCollectionInfo, PropertyInfo, ErrorInfo, Add Method (CatalogCollection), Remove Method (CatalogCollection)


MTS Packages Collection

As the top-level collection managed by the MTS Explorer, the Packages collection contains the packages installed on the local machine running MTS. Packages contain a set of components that run in the same server process, and define declarative security constructs that determine access to components at run time. The Packages collection supports the Add method and Remove method on the CatalogCollection object. In addition, the GetUtilInterface method of this collection returns a PackageUtil object which can be used to install and export packages.

The following table provides a list of the properties supported by the CatalogObject objects within the Packages collection.

Property	Description
Name	Name of the package. Data Type: String Default value: "New package" Access: Read/Write
ID	A universally unique identifier (UUID) for the package. Data Type: String Default value: A unique identifier is generated Access: Read/Write when using the Add method. Read-only  after using the Add method.
Description	Describes the package. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read/Write
IsSystem	Identifies an MTS system package. "N" signifies that the package is not a Transaction Server system package, and "Y" indicates that package is an MTS system package. Data Type: String Default value: "N" Access: Read only
Authentication	Sets authentication level for calls. Possible values are 0 through 6, which correspond to the Remote Procedure Call (RPC) authentication settings.  Data Type: Long Default value: 4 Access: Read/Write
ShutdownAfter	Sets the delay before shutting down a server process after it becomes idle. Shutdown latency ranges from 0 to 1440 minutes. Data Type: Long Default value: 3 Access: Read/Write
RunForever	Enables a server process to continue if a package is idle. If value is set to "Y", the server process will not shut down when left idle. If set to "N", the process will shut down according the value set by the ShutDownAfter property. Data Type: String Default value: "N" Access: Read/Write
SecurityEnabled	Checks the security credentials of any client that calls the package if value is set to "Y." Data Type: String Default value: "N" Access: Read/Write
Identity	Sets the server process identity for the package. Specify a valid Windows NT user account or "Interactive User" to have the package assume the identity of the current logged-on user. Data Type: String Default value: "Interactive User" Access: Read/Write
Password	Sets the password used by the server process to log on under the identity above. Data Type: String Default value: None Access: Write only
Activation	Sets the package level activation property to either "Local" or "Inproc". The Local setting determines that objects within the package will run within a dedicated local server process. A package running under the Local activation setting is a "server package". The Inproc activation setting means objects run in their creator's process. A package running under the Inproc activation setting is a "library package" Data Type:  String Default Value: "Local" Access:  Read/Write
Changeable	Sets whether changes to the package settings, or those of its components, are allowed (either programmatically, or through the MTS UI).
	Data Type:  String Default Value:  Y Access:  Read/Write
Deleteable	Sets whether the package or its components can be deleted (either programmatically, or through the MTS UI). Data Type:  String Default Value: "Y" Access:  Read/Write
CreatedBy	Informational string to describe the package creator. Data Type:   String Default Value: Empty string Access:  Read/Write
See Also

ComponentsInPackage, RolesInPackage, RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS ComponentsInPackage Collection

The ComponentsInPackage collection contains the set of components that run in the same server process and compose a package. This collection supports the Remove method. The Add method is not supported. You must use the ComponentUtil object to install components into the package.

The following table provides a list of the properties supported by the CatalogObjects within the ComponentsInPackage collection.

Property	Description
ProgID	The name that identifies the component. Data Type: String Default value: None Access: Read only
CLSID	The universally unique identifier (UUID) for the component. Data Type: String Default value: None Access: Read only
Transaction	Determines how a component supports transactions. Must be one of the following transaction settings: "Required" "Requires New" "Not Supported" "Supported" Data Type: String Default value: "Not supported" Access: Read/Write
Description	Describes the component. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read/Write
PackageID	Defines the identity of the owning package. Data Type: String Default value: None Access: Read only
PackageName	Defines the name of the owning package. Data Type: String Default value: "New Package" Access: Read only
ThreadingModel	Determines how instances of the component are assigned to threads for method execution. Possible values are those supported by Component Object Model (COM). Data Type: String Default value: None Access: Read only
SecurityEnabled	Checks the security credentials of any client that calls the component if value is set to "Y." Data Type: String Default value: "Y" Access: Read/Write
DLL	Displays the name of the DLL containing the component implementation. Data Type: String Default value: None Access: Read only
IsSystem	Identifies an MTS system component. "N" signifies that the package is not a Transaction Server system component, and "Y" indicates that package is an MTS system component. Data Type: String Default value: "N" Access: Read only
See Also

InterfacesForComponent, RolesForPackageComponent, RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS RemoteComponents Collection

Use the Microsoft Transaction Server (MTS) Explorer on a client computer to add remote component entries that see components installed on a remote server. This is often described as "pulling" remote component information from a server. Configuring remote components automatically copies proxy/stub DLLs and type libraries from the server to the client. The RemoteComponents collection supports the Remove method. This collection does not support the Add method on the CatalogCollection object. Instead you must call GetUtilInterface to obtain the RemoteComponentUtil object in order to add new remote components.

The following table provides a list of the properties supported by the CatalogObjects within the RemoteComponents collection.

Property	Description
ProgID	The name that identifies the remote component. Data Type: String Default value: None Access: Read only
CLSID	The universally unique identifier (UUID) for the component. Data Type: String Default value: None Access: Read only
Description	Describes the remote component. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read/Write
Server	Name of the server hosting the remote component. Data Type: String Default value: None Access: Read only
See Also

InterfacesForRemoteComponent, RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS InterfacesForComponent and InterfacesForRemoteComponent Collections

The InterfacesForComponent and InterfacesForRemoteComponent collections provide information about a selected interface. InterfacesForComponent or InterfacesForRemoteComponent collections are listed for each component, and can be used by an administrator to identify or manage the interface. These collections do not support the Add, Remove, or GetUtilInterface methods.

The following table provides a list of the properties supported by the CatalogObjects within the InterfacesForComponent and the InterfacesForRemoteComponent collections.

Property	Description
Name	Displays the friendly name of the interface. Data Type: String Default value: None Access: Read only
ID	Displays the unique interface identifier (IID).  Data Type: String Default value: None Access: Read only
Description	Describes the interface. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read/Write
ProxyCLSID	Displays the CLSID of the proxy/stub.  Data Type: String Default value: None Access: Read only
ProxyDLL	Displays the file name of the proxy/stub DLL. Data Type: String Default value: None Access: Read only
ProxyThreadingModel	Displays the threading model of the selected proxy/stub. Data Type: String Default value: None Access: Read only
TypeLibID	Displays the UUID of the type library. Data Type: String Default value: None Access: Read only
TypeLibVersion	Displays the version of the type library. Data Type: String Default value: None Access: Read only
TypeLibLangID	Displays the language identification number of the type library. Data Type: String Default value: None Access: Read only
TypeLibPlatform	Displays the platform of the type library. Data Type: String Default value: None Access: Read only
TypeLibFile	Displays the file name of the type library. Data Type: String Default value: None Access: Read only
See Also

MethodsForInterface (InterfacesForComponent only), RolesForPackageComponentInterface (InterfacesForComponent only), RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections

The RoleForPackageComponent and RolesForPackageComponentInterface collections contain the roles associated with a component or interface. You add existing roles to these collections from a package's RolesInPackage collection. The Add method is not supported by this collection. Use the RoleAssociationUtil methods to add roles to this collection. The CatalogCollection Remove method is supported by this collection.

The following table provides a list of the properties supported by the CatalogObject(s) within the RolesForPackageComponent and the RolesForPackageComponentInterface collections.

Property	Description
Name	Displays the name of the role associated with a component. Data Type: String Default value: None Access: Read only
ID	Displays the universally unique identifier (UUID) of the role. Data Type: String Default value: None Access: Read only
Description	Describes the role. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read only
See Also

RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS MethodsForInterface Collection

The MethodsForInterface collection contains the methods defined in an interface. Method properties are used to display information about the methods exposed by an interface. This collection does not support the Add, Remove, or GetUtilInterface methods.

The following table provides a list of the properties supported by the CatalogObjects within the MethodsForInterface collection.

Property	Description
Name	Displays the name of a method. Data Type: String Default value: None Access: Read only
Description	Describes the method. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read only
See Also

RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS RolesInPackage Collection

The RolesInPackage collection defines a class of users for a set of components in a package. Each role defines a set of users allowed to invoke interfaces on a component. Roles can be applied to both components and component interfaces. This collection supports the Add and Remove methods. This collection does not support the GetUtilInterface method.

The following table provides a list of the properties supported by the CatalogObjects within the RolesInPackage collection.

Property	Description
Name	The role name. Data Type: String Default value: "New Role" Access: Read/write
ID	The universally unique identifier (UUID) for the role. Data Type: String Default value: A unique identifier is generated. Access: Read/Write while using the Add method. After adding an object, Read-only.
Description	Describes the new Role. Description fields hold a maximum of 500 characters. Data Type: String Default value: None Access: Read/write
See Also

UsersInRole, RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS UsersInRole Collection

The UsersInRole collection lists the members of the class of users that have been authorized to invoke methods on the component or component interface associated with the role. This collection supports the Add and Remove methods. This collection does not support the GetUtilInterface method.

The following table provides a list of the properties supported by the CatalogObjects within the UsersInRole collection.

Property	Description
User	The name of an NT user account or group. Data Type: String Default value: "New User" Access: Read/Write while using the Add method. After adding, read-only.
See Also

RelatedCollectionInfo, PropertyInfo, ErrorInfo


MTS ErrorInfo Collection

The ErrorInfo collection is used to retrieve extended error information about methods that deal with multiple objects. This collection does not support the Add, Remove, or GetUtilInterface methods. Use the GetCollection method on a collection to access the ErrorInfo collection associated with the original collection. The ErrorInfo collection is accessible from any collection except ErrorInfo, RelatedCollectionInfo, and PropertyInfo. When calling methods on a utility object, extended error information may be created in the ErrorInfo collection associated with the collection used to create the utility object.

The following table provides a list of the properties supported by the CatalogObjects within the ErrorInfo collection.

Property	Description
Name	Name of the object or file. Data Type: String Default value: None Access: Read only.
ErrorCode	Error code for the object or file. Data Type: Long Default value: None Access: Read only
See Also

MTS LocalComputer Collection, MTS ComputerList Collection, MTS Packages Collection, MTS ComponentsInPackage Collection, MTS RemoteComponents Collection, MTS InterfacesForComponent and InterfacesForRemoteComponent Collections, MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections, MTS MethodsForInterface Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, MTS PropertyInfo Collection, MTS RelatedCollectionInfo Collection


MTS PropertyInfo Collection

The PropertyInfo collection is used to retrieve information about the properties that a specified collection supports. This collection does not support the Add, Remove, or GetUtilInterface methods. The PropertyInfo collection is accessible from any collection by using the GetCollection method.

The following table provides a list of the properties supported by the CatalogObject(s) within the PropertyInfo collection.

Property	Description
Name	Name of the property. Data Type: String Default value: None Access: Read only
See Also

MTS LocalComputer Collection, MTS ComputerList Collection, MTS Packages Collection, MTS ComponentsInPackage Collection, MTS RemoteComponents Collection, MTS InterfacesForComponent and InterfacesForRemoteComponent Collections, MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections, MTS MethodsForInterface Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, MTS ErrorInfo Collection, MTS RelatedCollectionInfo Collection


MTS RelatedCollectionInfo Collection

The RelatedCollectionInfo collection is used to retrieve information about other collections related to the collection from which this collection is called. The RelatedCollectionInfo collection is accessible from any collection by using the GetCollection method. The RelatedCollectionInfo collection will contain one object for each collection that is accessible from the original collection. Related collections follow the MTS Explorer folder hierarchy. This collection does not support the Add, Remove, or GetUtilInterface methods.

The following table provides a list of the properties supported by the CatalogObjects within the RelatedCollectionInfo collection.

Property	Description
Name	Name of the related collection. Data Type: String Default value: None Access: Read only
See Also

MTS LocalComputer Collection, MTS ComputerList Collection, MTS Packages Collection, MTS ComponentsInPackage Collection, MTS RemoteComponents Collection, MTS InterfacesForComponent and InterfacesForRemoteComponent Collections, MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections, MTS MethodsForInterface Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, MTS ErrorInfo Collection, MTS PropertyInfo Collection


MTS Visual Basic Error Codes

The following table lists the error codes returned by methods called on the MTS catalog collection and catalog utility objects.

Error code	Description
Visual Basic run-time error 5	Indicates one of the following: An invalid collection or property name was entered. An out parameter was NULL. The value is not one of the supported values or falls outside the supported range. The property is read-only. The property cannot be changed after the object is created. An invalid index was entered.
Visual Basic run-time  error 445	Object has been removed from the collection or the method is not supported on this object.
mtsErrObjectErrors	Errors were encountered processing some objects or file. See the ErrorInfo collection for object and file-specific error codes.
mtsErrNoUser	User ID for user in role is not valid.
mtsErrUserPasswdNotValid	Package identity user ID and/or password are not valid.
mtsErrAuthenicationLevel	Required authentication level (package privacy) could not be set for package updates.
mtsErrPDFReadFail	An error occurred reading the package file.
mtsErrPDFVersion	Package file version is invalid.
mtsErrBadPath	Package file path is invalid.
mtsErrPackageExists	Package with the same ID is already installed.
mtsErrRoleExists	A role with the same ID is already installed. The role ID in the package file is likely corrupted.
mtsErrCantCopyFile	Errors occurred copying one or more files to the install directory.
mtsErrInvalidUserids	One or more user IDS for roles were invalid.
mtsErrCLSIDOrIIDMismatch	One or more component or interface identifiers in a component DLL do not match the identifiers saved in the package file. The package file is out of date.
mtsErrPackDirNotFound	Package install directory is invalid due to general registry read/write errors.
mtsErrPDFWriteFail	An error occurred writing the package file.
mtsErrNoTypeLib	Could not find the type library for one or more components.
The following table lists the object or file-specific error codes returned in ErrorInfo collections.

Error code	Description
mtsErrObjectInvalid	One or more object properties is corrupted or invalid.
mtsErrKeyMissing	One or more objects is not found in the catalog data store.
mtsErrAlreadyInstalled	Component is already installed.
mtsErrDownloadFailed	One or more component files could not be copied to the client.
mtsErrRemoteInterface	No interface information is available for the component. Component files could not be downloaded.
mtsErrCoReqCompInstalled	Component in the same DLL file is already installed.
mtsErrNoRegistryCLSID	Component's CLSID is corrupted.
mtsErrBadRegistryProgID	Component's ProgID is corrupted.
mtsErrDllLoadFailed	Component's DLL could not be loaded.
mtsErrDllRegisterServer	DllRegisterServer method failed during component self-registration.
mtsErrNoServerShare	No file share is available on the server to copy component files from the network path.
mtsErrNoAccessToUNC	Network path registered for this component could not be accessed.
mtsErrBadRegistryLibID	Component type library ID is corrupted.
mtsErrTreatAs	Component TreatAs key was found, but is not supported.
mtsErrBadForward	IID forward entry is corrupted.
mtsErrBadIID	IID is corrupted.
mtsErrRegistrarFailed	Component registrar method failed during component install.
mtsErrCompFileDoesNotExist	Component file does not exist.
mtsErrCompFileLoadDLLFail	DLL file could not be loaded.
mtsErrCompFileGetClassObj	DllGetClassObject function call failed during the DLL self-registration process.
mtsErrCompFileClassNotAvail	Class coded in the type library was not supported.
mtsErrCompFileBadTLB	Type library was corrupted.
mtsErrCompFileNotInstallable	File does not contain COM components or type library information.
mtsErrNotChangeable	Changes to this object and sub-objects have been disabled.
mtsErrNotDeletable	Delete function for this object has been disabled.
mtsErrSession	Catalog version is not supported.
The following tables lists general read and write registry errors.

Error Code	Description
mtsErrNoRegistryRead	Access control failure reading a registry key.
mtsErrNoRegistryWrite	Access control failure writing a registry key.
mtsErrNoRegistryRepair	Access control failure writing a registry key.


MTS Administration Object Methods

The following topics list the methods of the MTS administration objects:

Add Method (CatalogCollection)

AddEnabled Property (CatalogCollection)

AssociateRole Method (RoleAssociationUtil)

AssociateRoleByName Method (RoleAssociationUtil)

Connect Method (Catalog)

Count Property (CatalogCollection)

DataStoreMajorVersion Property (CatalogCollection)

DataStoreMinorVersion Property (CatalogCollection)

ExportPackage Method (PackageUtil)

GetCLSIDs Method (ComponentUtil)

GetCollection Method (Catalog)

GetCollection Method (CatalogCollection)

GetUtilInterface Method (CatalogCollection)

ImportComponent Method (ComponentUtil)

ImportComponentByName Method (ComponentUtil)

InstallComponent Method (ComponentUtil)

InstallPackage Method (PackageUtil)

InstallRemoteComponent Method (RemoteComponentUtil)

InstallRemoteComponentByName Method (RemoteComponentUtil)

IsPropertyReadOnly Property (CatalogObject)

IsPropertyWriteOnly Property (CatalogObject)

Item Property (CatalogCollection)

Key Property (CatalogObject)

MajorVersion Property (Catalog)

MinorVersion Property (Catalog)

Name Property (CatalogObject)

Name Property (CatalogCollection)

Populate Method (CatalogCollection)

PopulateByKey Method (CatalogCollection)

Remove Method (CatalogCollection)

RemoveEnabled Property (CatalogCollection)

SaveChanges Method (CatalogCollection)

ShutdownPackage Method

Valid Property (CatalogObject)

Value Property (CatalogObject)

See the Automating MTS Administration topic for sample code that demonstrates how these methods are used to program administration using Microsoftｮ Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).


Add Method (CatalogCollection)

Adds a member to a collection object and returns the CatalogObject object.

Syntax

object.Add

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

Call the Add method to create a new object in a collection. This method is supported in the following collections:

Packages

RolesInPackage

UsersInRole

To install or create objects in other collections, use the catalog utility interfaces. Note that you must call the SaveChanges method to write the new object to the catalog data store.

For a list of the MTS collections and their properties, see Using MTS Collections.

See Also

MTS Packages Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, AddEnabled Property (CatalogCollection)


AddEnabled Property (CatalogCollection)

Returns a Boolean value indicating whether the Add method is enabled on this collection.

Syntax

object.AddEnabled

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

If the value returned is True, then you can call the Add method to create a new object in a collection. If the value returned is False, you must use the catalog utility object methods to create a new object.

For a list of the MTS collections and their properties, see the Using MTS Collections topic.

See Also

Add Method (CatalogCollection)


AssociateRole Method (RoleAssociationUtil)

Associates a role with a component or component interface.

Syntax

object.AssociateRole(ID)

Parameters

object
Required. An object variable that evaluates to a RoleAssociationUtil object.

ID
Required. A String expression that specifies the role ID of the roles to associate with the object.

Remarks

The changes are applied immediately to the catalog.

For a list of properties supported by Role collections,see the Using MTS Collections topic.

See Also

AssociateRoleByName Method (RoleAssociationUtil)


AssociateRoleByName Method (RoleAssociationUtil)

The AssociateRoleByName method associates a role with a specified component or component interface.

Syntax

object.AssociateRoleByName(name)

Parameters

object
Required. An object variable that evaluates to a RoleAssociationUtil utility object.

name
Required; String. An expression providing the name of the role to associate with a component or component interface.

Remarks

The changes are applied immediately to the catalog. For a list of properties supported by Role collections,see the Using MTS Collections topic.

See Also

AssociateRole Method (RoleAssociationUtil)


Connect Method (Catalog)

Connects to a catalog and returns a root collection.

Syntax

set root object.Connect(name)

Parameters

root
Required. String containing the root collection that serves as a starting point to locate top-level collections.

object
Required. An object variable that evaluates to a catalog object.

name
Required; String. String containing the name of a remote computer. To connect to a local computer, supply an empty string as this argument.

Remarks

The Connect method returns a root collection, which is bound to the connected computer. A root collection serves as a starting point to locate top-level collections, and does not contain any objects or properties.

Note that you can also use the GetCollection method to locate a package on the local computer without first having to call the Connect method.

You can get the following collections from the root collection:

Packages

RemoteComponents

RelatedCollectionInfo

ComputerList

LocalComputer

PropertyInfo

For a list of the MTS collections and their properties, see the Using MTS Collections topic.

See Also

GetCollection Method (CatalogCollection)


Count Property (CatalogCollection)

Returns an integer value indicating the number of objects in a collection.

Syntax

object.Count

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

Upon instantiation, a CatalogCollection object returns a count of zero. Call the Populate method to read from the CatalogCollection object, and then use the Count method to return the number of objects in the collection.

for a list of the MTS collections and their properties, see the Using MTS Collections topic.

See Also

Populate Method (CatalogCollection)


DataStoreMajorVersion Property (CatalogCollection)

Returns an integer value indicating the major version number of the catalog.

Syntax

object.DataStoreMajorVersion

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

See Also

DataStoreMinorVersion Property (CatalogCollection),


DataStoreMinorVersion Property (CatalogCollection)

Returns an integer value indicating the minor version number of the catalog.

Syntax

object.DataStoreMajorVersion

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

See Also

DataStoreMajorVersion Property (CatalogCollection)


ExportPackage Method (PackageUtil)

Exports a package.

Syntax

object.ExportPackage(PackID, FileName, Options)

Parameters

object
Required. An object variable that evaluates to a PackageUtil object.

PackID
Required; String. An object variable that specifies the package ID of the package to export.

FileName
Required; String. An object variable that provides the name of the package file to export.

Options
Required; Long. An integer value specifying export options. This parameter can be 0 or MtsExportUsers, which includes users in roles in the package file.


GetCLSIDs Method(ComponentUtil)

Returns an array of installable class identifiers (CLSIDs) in the component DLL and/or type library.

Syntax

object.GetCLSIDs(bstrDLLFile, bstrTypeLibFile, aCLSIDs)

Parameters

BstrDLLFile
Required; String. A string variable that evaluates to the path of the DLL that you want checked.

BstrTypeLibFile
Required; String. A string variable that evaluates to the path of the type library that you want checked. If the type library is embedded with the DLL (as is the case with DLLs generated by Microsoft Visual Basic), this parameter should be an empty string).

aCLSIDS
Required; Variant. An output array of CLSIDs (VARIANTS) that can be installed from the supplied DLL and/or type library.


GetCollection Method (Catalog)

Instantiates a CatalogCollection object.

Syntax

set x object.GetCollection(Name)

Parameters

x
Required. An object variable (a variant, or object variable, or a CatalogCollection variable) for the returned collection.

object
Required. An object variable that evaluates to a catalog object.

Name
Required; String. A string expression containing the name of the collection to instantiate.

Remarks

You can use this method to get the following collections:

Packages

ComputerList

LocalComputer

RemoteComponents

RelatedCollectionInfo

After using the GetCollection method, you must fill the object by calling the Populate method. See the Populate method topic for further detail.

For a list of the MTS collections and their properties, see the Using MTS Collections topic..


GetCollection Method (CatalogCollection)

Retrieves a collection from the catalog.

Syntax

set x  object.GetCollection(name, key)

Parameters

x
Required. An object variable (a variant, or object variable, or a CatalogCollection variable) for the returned collection.

object
Required. An object variable that evaluates to a CatalogCollection object.

name
Required. A String expression containing the name of the collection to instantiate.

key
Required. A Variant expression containing the key of the object from which to navigate.

Remarks

Note that the GetCollection method gets an empty collection; you must call the Populate method to fill the collection.

For a list of the MTS collections and their properties, see the Using MTS Collections topic.

See Also

Populate Method (CatalogCollection),


GetUtilInterface Method (CatalogCollection)

Instantiates a utility object for the collection.

Syntax

set util  object.GetUtilInterface

Parameters

util
Required. An object variable that evaluates to a catalog utility object.

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

Call the GetUtilInterface method to instantiate any one of the PackageUtil, ComponentUtil, RemoteComponentUtil, and RoleAssociationUtil utility objects. This method is only supported on Packages, ComponentsInPackage, RemoteComponents, RolesForPackageComponent, and RolesForPackageComponentInterface collections.

For a list of the MTS collections and their properties, see the Using MTS Collections topic.


ImportComponent Method (ComponentUtil)

Imports a component that is already registered as an in-process (in-proc) server.

Syntax

object.ImportComponent(CLSID)

Parameters

object
Required. An object variable that evaluates to a ComponentUtil object.

CLSID
Required; String. An expression containing the CLSID of the component to be installed.

Remarks

The changes are applied immediately to the catalog.

For a description of the Component collection and its associated properties, see the Using MTS Collections topic.

See Also

ImportComponentByName Method (ComponentUtil)


ImportComponentByName Method (ComponentUtil)

Imports a component that is already registered as an in-process server by the component's programmatic identifier (ProgID).

Syntax

object.ImportComponentByName(ProgID)

Parameters

object
Required. An object variable that evaluates to a ComponentUtil object.

ProgID
Required. A String expression identifying the ProgID of the component to be installed.

Remarks

The changes are applied immediately to the catalog. For a description of the Component collection and its associated properties, see the Using MTS Collections topic.

See Also

ImportComponent Method (ComponentUtil)


InstallComponent Method (ComponentUtil)

Installs a component into a package.

Syntax

object.InstallComponent(filepath, typelibrary, proxy-stub)

Parameters

object
Required. An object variable that evaluates to a ComponentUtil object.

filepath
Required. A String expression that provides the file path of the DLL containing the components to install.

typelibrary
Required. A String expression that provides the file path of the type library to use. Pass an empty string as this argument if the type library is embedded in the DLL.

proxy-stub
Required. A String expression that provides the file path of a custom proxy-stub DLL to use. Pass an empty string as this argument if there is no custom proxy-stub DLL.

Remarks

The changes are applied immediately to the catalog.

For a description of the Components collection and its associated properties, see the Using MTS Collections topic.

See Also

InstallRemoteComponent Method (RemoteComponentUtil), InstallRemoteComponentByName Method (RemoteComponentUtil)


InstallPackage Method (PackageUtil)

Installs a component or components that are valid within a package's collection.

Syntax

object.InstallPackage(FileName, InstallPath, options)

Parameters

object
Required. An object variable that evaluates to a Package utility object.

FileName
Required; String. String expression evaluating to the name of the package to install.

InstallPath
Required; String. String expression evaluating to the install path for component files.

options
Required; Long. A long value specifying install options. This parameter can be 0 or mtsInstallUsers, which adds users saved in the package file. If this option is not specified, users saved in the package file are not installed.

Remarks

All component files must be in the same directory of the package file. Component files arecopied to the install path specified as an argument of the InstallPackage method.

The changes are applied immediately to the catalog.

For a description of the Components collection and its associated properties, see the Using MTS Collections topic..


InstallRemoteComponent Method (RemoteComponentUtil)

Pulls remote components from a package on a remote server.

Syntax

object.InstallRemoteComponent(computer, PackID, CLSID)

Parameters

object
Required. An object variable that evaluates to a RemoteComponentUtil object.

computer
Required; String. A string expression providing the name of the remote computer.

PackID
Required; String. A string expression providing the package identification of the package containing the remote component.

CLSID
Required; String. A string expression containing the CLSID of the remote component.

Remarks

The changes are applied immediately to the catalog.

See the Working with Remote MTS Computers topic for a complete description of how to pull components from a remote server.

See Also

InstallRemoteComponentByName Method (RemoteComponentUtil)


InstallRemoteComponentByName Method (RemoteComponentUtil)

Pulls remote components by name from the package on a remote server.

Syntax

object.InstallRemoteComponentByName(computer, PackName, ProgID)

Parameters

object
Required. An object variable that evaluates to a RemoteComponentUtil object.

computer
Required; String. A string expression providing the name of the remote computer.

PackName
Required; String. A string expression providing the name of the package containing the remote component.

ProgID
Required; String. A string value containing the ProgID of the remote component.

Remarks

The changes are applied immediately to the catalog. See the Working with Remote MTS Computers topic for a complete description of how to pull components from a remote server.

See Also

InstallRemoteComponent Method (RemoteComponentUtil)


IsPropertyReadOnly Property (CatalogObject)

Returns a Boolean value that indicates if the property for an object is set to read-only.

Syntax

object.IsPropertyReadOnly(value)

Parameters

object
Required. An object variable that evaluates to a catalog object property.

value
Required. The name of the value for which to check the read-only property.

Remarks

If the value returned by the IsPropertyReadOnly method is True, then you cannot modify the property. If the value returned is False, you can modify the property using the Value property.


IsPropertyWriteOnly Property (CatalogObject)

Returns a Boolean value that indicates if the property for an object is set to write-only.

Syntax

object.IsPropertyWriteOnly(propertyname)

Parameters

object
Required. An object variable that evaluates to a catalog object property.

propertyname
Required. The name of the property for which to check the write-only status.

Remarks

If the value returned by the IsPropertyWriteOnly method is True, then you can write but not read the property value. If the value returned is False, you can read the property value.

See Also

IsPropertyReadOnly Property (CatalogObject)


Item Property (CatalogCollection)

Gets a specific object in a collection.

Syntax

object.Item(index)

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

index
Required; Long. A zero-based index that specifies the position of a member of the collection. Must be a number from 0 through the value of the collection's Count property -1.


Key Property (CatalogObject)

Gets the value of the key of the object.

Syntax

object.Key

Parameters

object
Required. An object variable that evaluates to a CatalogObject object.

Remarks

All catalog objects have a key. The object key is a single property that uniquely identifies the object. To access a related collection using the GetCollection method, provide the key of the object from which you want to navigate (such as the package identifier). The following table provides the key property for each collection supported:

Collection	Key Property
Packages	ID
ComponentsInPackage	CLSID
RolesInPackage	ID
RolesForPackageComponent	ID
RolesForPackageComponentInterface	ID
UsersInRole	User
InterfacesForComponent	IID
InterfacesForRemoteComponent	IID
RemoteComponents	CLSID
MethodsForInterface	Name


MajorVersion Property (Catalog)

Returns an integer value indicating the major version number of the catalog.

Syntax

object.MajorVersion

Parameters

object
Required. An object variable that evaluates to a catalog object.

See Also

MinorVersion Property (Catalog)


MinorVersion Property (Catalog)

Returns an integer value indicating the minor version number of the catalog.

Syntax

object.MinorVersion

Parameters

object
Required. An object variable that evaluates to a catalog object.

See Also

MajorVersion Property (Catalog)


Name Property (CatalogObject)

Gets the name of an object.

Syntax

object.Name

Parameters

object
Required. An object variable that evaluates to a catalog object.

Remarks

All catalog objects have a name property. The following table provides the name property for each collection supported:

Collection	Name Property
Packages	Name
ComponentsInPackage	ProgID
RolesInPackage	Name
RolesForPackageComponent	Name
RolesForPackageComponentInterface	Name
UsersInRole	User
InterfacesForComponent	Name
InterfacesForRemoteComponent	Name
RemoteComponents	ProgID
MethodsForInterface	Name


Name Property (CatalogCollection)

Gets the name of the collection.

Syntax

object.Name

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

See the Using MTS Collections topic for a list of properties supported by each MTS collection.


Populate Method (CatalogCollection)

Fills a collection with objects from the catalog.

Syntax

object.Populate

Parameters

object
Required. An object variable that evaluates to the CatalogCollection object that you would like to fill.

Remarks

The Populate method reads the contents of the CatalogCollection object. Any changes that are still pending (such as property changes, objects added, or objects removed) are lost. See the SaveChanges method topic for instruction on how to preserve changes made to a CatalogCollection object.


PopulateByKey Method (CatalogCollection)

Populates the collection with information for the specified objects.

Syntax

object.PopulateByKey(aCLSIDs)

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

aCLSIDS
Required; Variant. An array of object keys (VARIANTS) denoting which objects should have their information read from the catalog.


Remove Method (CatalogCollection)

Removes an item from an object given the index position.

Syntax

object.Remove(index)

Parameters

object
Required; String. An object variable that evaluates to a CatalogCollection object.

index
Required; Long. A zero-based index indicating the position of the object to remove.

Remarks

The object is removed from the collection and all objects with higher indices are shifted up. Note that the Count property of a collection changes after the Remove method has been called.

Call the SaveChanges method to save the changes made to the collection using the Remove method.


RemoveEnabled Property (CatalogCollection)

Returns a Boolean value indicating that you can use the Remove method to delete an object from the collection.

Syntax

object.RemoveEnabled

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

If the value returned is True, then you can call the Remove method to remove an object from the collection. If the value returned is False, objects cannot be removed from the collection.


SaveChanges Method (CatalogCollection)

Saves changes to a collection in the catalog, and returns an integer indicating the number of changes applied to the collection.

Syntax

object.SaveChanges

Parameters

object
Required. An object variable that evaluates to a CatalogCollection object.

Remarks

The SaveChanges method works exclusively on the collection on which you call it, and applies all pending changes to the catalog. If no changes are pending, then the method returns zero.

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ShutdownPackage method (PackageUtilObject); PackageUtil methods, ShutdownPackage; scriptable object methods, ShutdownPackage
ShutdownPackage Method (PackageUtil)

Initiates the shutting down of a package. Shutting down a package terminates that application's process.

Syntax

object.ShutdownPackage(bstrPackageID)

Parameters

object
Required. An object variable that evaluates to a PackageUtil object.

bstrPackageID
Required. A string variable that evaluates to the PackageID of a Package CatalogObject.

Remarks

The ShutdownPackage method shuts down a single package process.

See the Using MTS Collections topic for a list of the MTS collections and their properties.


Valid Property (CatalogObject)

Returns a Boolean value indicating whether all the object properties were successfully read from the catalog.

Syntax

object.Valid

Parameters

object
Required. An object variable that evaluates to a CatalogObject.

Remarks

If this property is False it indicates that one or more object properties could not be read from the catalog during a call to Populate. This property will be True for objects that have been added to the collection using the Add method.


Value Property (CatalogObject)

Gets or sets a value for an object property.

Syntax

object.Value(property) value

Parameters

object
Required. An object variable that evaluates to a CatalogObject.

property
Required. A String expression of any type that specifies the name of the property whose value to get or set.

value
Required. A String expression that specifies the value of the property to get or set.

Remarks

See the Using MTS Collections topic for a description the properties supported by the MTS administration objects.


Automating MTS Administration With Visual C++

The topics in this section describe administration interfaces supported by Microsoft Transaction Server (MTS). This reference describes the following topics:

MTS Visual C++ Error Codes

ICatalog

ICatalogObject

ICatalogCollection

IPackageUtil

IComponentUtil

IRemoteComponentUtil

IRoleAssociationUtil

The ICatalog, ICatalogObject, and ICatalogCollection interfaces provide top-level functionality such as creating and modifying objects. The ICatalog interface enables you to connect to specific servers and access collections. Call the ICatalogCollection interface to enumerate, create, delete, and modify objects, as well as to access related collections. The ICatalogObject interface is used to get and set properties on an object.

The utility interfaces (IRemoteComponentUtil and IRoleAssociationUtil)  allows you to program very specific tasks for collection types, such as associating a role with a user or class of users.


MTS Visual C++ Error Codes

The following is a list of the error codes returned by methods called on the  catalog collection and catalog utility interfaces.

E_INVALIDARG
Indicates one of the following:

An invalid collection or property name was entered.

An out parameter was NULL.

The value is not one of the supported values or falls outside the supported range.

The property is read-only.

The property cannot be changed after the object is created.

An invalid index was entered.

E_NOTIMPL
Object has been removed from the collection and is not supported on this collection.

E_MTS_OBJECTERRORS
Errors were encountered processing some objects or file. See the ErrorInfo collection for object/file-specific error codes.

E_MTS_NOUSER
User ID for user in role is not valid.

E_MTS_USERPASSWDNOTVALID
Package identity user ID and/or password are not valid

E_MTS_AUTHENICATIONLEVEL
Required authentication level (package privacy) could not be set for package updates.

E_MTS_PDFREADFAIL
An error occurred reading the package file.

E_MTS_PDFVERSION
Package file version is invalid.

E_MTS_BADPATH
Package file path is invalid.

E_MTS_PACKAGEEXISTS
Package with the same ID is already installed.

E_MTS_ROLEEXISTS
A role with the same ID is already installed. The role ID in the package file is likely corrupted.

E_MTS_CANTCOPYFILE
Errors occurred copying one or more files to the install directory.

E_MTS_INVALIDUSERIDS
One or more user IDS for roles were invalid.

E_MTS_CLSIDORIIDMISMATCH
One or more component/interface identifiers in a component DLL does not match the identifiers saved in the package file. The package file is out of date.

E_MTS_PACKDIRNOTFOUND
Package install directory is invalid due to general registry read/write errors.

E_MTS_PDFWRITEFAIL
An error occurred writing the package file.

E_MTS_NOTYPELIB
Could not find the type library for one or more components.

The following is a list of the object or file-specific error codes returned in ErrorInfo collections:

E_OBJECTINVALID
One or more object properties is corrupted or invalid.

E_KEYMISSING
One or more objects is not found in the catalog.

E_ALREADYINSTALLED
Component is already installed.

E_DOWNLOADFAILLED
One or more component files could not be copied to the client.

E_REMOTEINTERFACE
No interface information is available for the component. Component files could not be downloaded.

E_COREQCOMPINSTALLED
Component in the same DLL file is already installed.

E_NOREGISTRYCLSID
Component's CLSID is corrupted.

E_BADREGISTRYPROGID
Component's ProgID is corrupted.

E_DLLLOADFAILED
Component's DLL could not be loaded.

E_DLLREGISTERSERVER
DllRegisterServer method failed during component self-registration.

E_NOSERVERSHARE
No file share is available on the server to copy component files from the network path.

E_NOACCESSTOUNC
Network path registered for this component could not be accessed.

E_BADREGISTRYLIBID
Component type library ID is corrupted.

E_TREATAS
Component TreatAs key was found, but is not supported.

E_BADFORWARD
IID forward entry is corrupted.

E_BADIID
IID is corrupted.

E_REGISTRARFAILED
Component registrarmethod failed during component install.

E_COMFILE_DOESNOTEXIST
Component file does not exist.

E_COMFILE_LOADDLLFAIL
DLL file could not be loaded.

E_COMFILE_GETCLASSOBJ
DllGetClassObject method call failed during the DLL self-registration process.

E_COMFILE_CLASSNOTAVAIL
Class coded in the type library was not supported.

E_COMFILE_BADTLB
Type library was corrupted.

E_COMFILE_NOTINSTALLABLE
File does not contain COM components or type library information.

The following is a list of general read and write registry errors:

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

E_MTS_NOTCHANGEABLE
Changes to this object and sub-objects have been disabled.

E_MTS_NOTDELETABLE
Delete function for this object has been disabled.

E_MTS_SESSION
Server catalog version is not supported.


MTS ICatalog Interface

The Catalog object enables you to connect to specific servers and access collections. The ICatalog interface contains the following methods:

ICatalog::GetCollection

ICatalog::Connect

ICatalog::get_MajorVersion

ICatalog::get_MinorVersion


ICatalog::GetCollection

The GetCollection method retrieves a local collection without reading any objects from the catalog.

Syntax

HRESULT ICatalog::GetCollection(

BSTR	bstrCollName
IDispatch **	ppCatalogCollection);
Parameters

bstrCollName [in]
BSTR containing the name of the collection to retrieve from the catalog.

ppCatalogCollection [out]
Pointer to a pointer to the CatalogCollection object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid collection name passed as a parameter. Can also indicate that an Out parameter is NULL.


ICatalog::Connect

The Connect method connects to a remote computer and returns a root collection, which is bound to a remote computer.

HRESULT ICatalog::Connect(

BSTR	bstrConnectString
IDispatch **	ppCatalogCollection);
Parameters

bstrConnectString [in]
BSTR expression containing the name of a remote computer.

ppCatalogCollection [out]
Pointer to a pointer to the CatalogCollection object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Comments

A root collection serves as a starting point to locate packages, and contains neither objects nor properties. Note that you can also use the GetCollection method to get a top-level collection on a local server without using the Connect method.


ICatalog::get_MajorVersion

The get_MajorVersion method returns the major version number of an administration object.

HRESULT ICatalog::get_MajorVersion(

long*	retval);
Parameters

retval [out]
Pointer to the major version number of the MTS object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Comments

Call the get_MajorVersion method and the get_MinorVersion method to determine if you are using the most current version of MTS


ICatalog::get_MinorVersion

The get_MinorVersion method retrieves the minor version number of an MTS administration object.

HRESULT ICatalog::get_MinorVersion(
long * 	retval
);

Parameters

retval [out]
Pointer to the minor version number of the MTS object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Comments

Call the get_MajorVersion method and the get_MinorVersion method to determine if you are using the most current version of MTS.


MTS ICatalogCollection Interface

The CatalogCollection object can be used to enumerate objects, create, delete, and modify objects, and access related collections. The ICatalogCollection interface contains the following methods:

ICatalogCollection::get_NewEnum

ICatalogCollection::get_Item

ICatalogCollection::get_Count

ICatalogCollection::Remove

ICatalogCollection::Add

ICatalogCollection::Populate

ICatalogCollection::SaveChanges

ICatalogCollection::GetCollection

ICatalogCollection::get_Name

ICatalogCollection::get_AddEnabled

ICatalogCollection::get_RemoveEnabled

ICatalogCollection::GetUtilInterface

ICatalogCollection::get_DataStoreMajorVersion

ICatalogCollection:: get_DataStoreMinorVersion

ICatalogCollection::PopulateByKey


ICatalogCollection::get_NewEnum

The get_NewEnum method returns the IEnumVariant enumerator interface.

HRESULT ICatalogCollection::get_NewEnum(

IUnknown **	ppEnumVariant);
Parameters

ppEnumVariant [out]
Pointer to a pointer to the IEnumVariant interface.

Return Values

S_OK
Method completed successfully.

INVALIDARG
Out parameter is NULL.


ICatalogCollection::get_Item

The get_Item method returns an object from the collection represented by the index.

HRESULT ICatalogCollection::get_Item(

long	1Index
IDispatch**	ppCatalogObject);
Parameters

1Index [in]
Index to the object in the collection.

ppCatalogObject [out]
Pointer to a pointer to the Catalog object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out of range of index.

Comments

A collection object contains zero or more items (all MTS collections are zero-based).

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::get_Count

The get_Count method returns the number of objects in the collection.

HRESULT ICatalogCollection::get_Count(

long *	retval);
Parameters

retval [out]
Pointer to the number of elements in the object collection.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::Add

The Add method adds a default object to the collection and returns a pointer to the new object.

HRESULT ICatalogCollection::Add(

IDispatch **	ppCatalogObject);
Parameters

ppCatalogObject [out]
Pointer to a pointer to the new Catalog object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

E_NOTIMPL
Not supported on this collection.

Remarks

To update the objects in a collection, call the Add method to create a new object either before or after populating a collection.

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::Populate

The Populate method reads the collection objects from the catalog.

HRESULT ICatalogCollection::Populate( );

Return Values

S_OK
Method completed successfully.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

E_MTS_OBJECTERRORS
Collection was read but some objects were invalid. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

Remarks

You call the Populate method to fill a package collection with objects from the catalog. This method uses the CoCreateInstance function internally, so CoCreateInstance error codes are included in the Populate method's return values.

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::SaveChanges

The SaveChanges method saves changes to the collection into the catalog.

HRESULT ICatalogCollection::SaveChanges(

long *	retval);
Parameters

retval [out]
Number of changes applied to the collection.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

E_MTS_OBJECTERRORS
Errors were encountered processing some objects. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOUSER
User ID is invalid.

E_MTS_USERPASSWDNOTVALID
Package identity user ID and/or password are invalid.

E_MTS_AUTHENTICATIONLEVEL
Required authentication level (package privacy) could not be set for package updates.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

CLASS_E_NOAGGREGATION
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

You must call this method after modifying any object in the collection. The SaveChanges method works exclusively on the collection on which it is called. This method also applies all pending changes to objects within a given collection. This method uses the CoCreateInstance function internally, so CoCreateInstance error codes are included in the SaveChanges method's return values.

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::GetCollection

The GetCollection method retrieves a collection related to a specific object. Data is not read from the catalog. See the Populate method topic for more information.

HRESULT ICatalogCollection::GetCollection(

BSTR	bstrCollName
VARIANT	varObjectKey
IDispatch **	ppCatalogCollection);
Parameters

bstrCollName [in]
BSTR containing the name of the collection.

VarObjectKey [in]
Value of the object key.

retval [out]
Pointer to a pointer to the CatalogCollection object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid collection name passed as a parameter. Can also indicate that an Out parameter is NULL.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::get_Name

The get_Name method gets the name of a collection.

HRESULT ICatalogCollection::get_Name(
VARIANT*	retval);

Parameters

retval [out]
Pointer to the name of the collection.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::get_AddEnabled

The get_AddEnabled method returns a value that indicates if the Add method is supported in this collection.

HRESULT ICatalogCollection::get_AddEnabled(
VARIANT_BOOL*	varAddEnabled);

Parameters

VarObjectKey [out]
Boolean value indicating if the Add method is supported in this collection.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::Remove

The Remove method removes an item from a collection, given the index of the item.

HRESULT ICatalogCollection::Remove(
long	1Index);

Parameters

1Index [in]
Index position of the object to remove.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid index was entered.

E_NOTIMPL
Collection does not support removing objects.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::get_RemoveEnabled

The get_RemoveEnabled method returns a value that indicates if the Remove method is supported in this collection.

HRESULT ICatalogCollection:: get_RemoveEnabled(
VARIANT_BOOL * 	boolRemoveEnabled);

Parameters

boolRemoveEnabled [out]
Boolean value indicating if the Remove method is supported in this collection.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::GetUtilInterface

The GetUtilInterface method returns a pointer to the interface of the utility object for a package, component, remote component, or role collection.

HRESULT ICatalogCollection::GetUtilInterface(
IDispatch**	ppUtil);

Parameters

ppUtil [out]
Pointer to a pointer to the interface on a utility object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

E_NOTIMPL
Not supported on this collection.

Remarks

Call the GetUtilInterface method to program your application for specific administration tasks, such as creating a package or installing a component.

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogCollection::get_DataStoreMajorVersion

The get_DataStoreMajorVersion method returns the major version number of the catalog from which you get the collection.

HRESULT ICatalogCollection::get_DataStoreMajorVersion(
long * 	retval);

Parameters

retval [out]
Pointer to a pointer to the MTS major version number.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

See Also

get_DataStoreMinorVersion


ICatalogCollection::get_DataStoreMinorVersion

The get_DataStoreMinorVersion method returns the minor version number of the catalog from which you get a collection.

HRESULT ICatalogCollection:: get_DataStoreMinorVersion(
long * 	retval);

Parameters

retval [out]
Pointer to a pointer to the MTS minor version number.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

See Also

get_DataStoreMajorVersion


ICatalogCollection::PopulateByKey

The PopulateByKey method populates the collection with information for the specified objects.

HRESULT ICatalogCollection::PopulateByKey(
SAFEARRAY * 	saKeys);

Parameters

saKeys [in]
Pointer to a safearray of VARIANTs containing the CLSIDs of components for which the collection object should refresh its information.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


MTS ICatalogObject Interface

The CatalogObject object provides methods to get and set properties on an object. The ICatalogObject interface contains the following methods:

ICatalogObject::get_Value

ICatalogObject::put_Value

ICatalogObject::get_Key

ICatalogObject::get_Name

ICatalogObject::IsPropertyReadOnly

ICatalogObject::IsPropertyWriteOnly

ICatalogObject::get_Valid


ICatalogObject::get_Value

The get_Value method gets a property value of an object in a collection.

HRESULT ICatalogObject::get_Value(

BSTR	bstrPropName
VARIANT *	retval);
Parameters

bstrPropName [in]
BSTR expression containing the name of the property.

retval [out]
Pointer to the value of the property.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid property name passed as a parameter. Can also indicate that an Out parameter is NULL.

E_NOTIMPL
Object has been removed from the collection.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogObject::put_Value

The put_Value method sets the property value of an object in a collection.

HRESULT ICatalogObject::put_Value(

BSTR	bstrPropName
VARIANT	val);
Parameters

bstrPropName [in]
BSTR containing the name of the property to set.

val [in]
Variant containing the new value for the property.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid property name entered. Can also indicate either the property value is not one of the supported values or falls outside the supported range, the property is read-only, or the property cannot be changed after the object is created.

E_NOTIMPL
Object has been removed from the collection.

Remarks

See the Using MTS Collections topic for a list of the MTS collections and their properties.


ICatalogObject::get_Key

The get_Key method gets the value of the Key property.

HRESULT ICatalogObject::get_Key(

VARIANT*	retval);
Parameters

retval [out]
Pointer to the value of the Key property.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

E_NOTIMPL
Object has been removed from the collection.

Comments

All MTS objects have a key. The object key is a single property that uniquely identifies the object. To create a related collection in your Package collection object, provide the key of the object from which you want to navigate (such as the package identifier). The following table provides the key property for each collection supported by the MTS Explorer.

Collection	Key Property
Packages	ID
ComponentsInPackage	CLSID
RolesInPackage	ID
RolesForPackageComponents	ID
UsersInRole	User
InterfacesForComponent	IID
InterfacesForRemoteComponent	IID


ICatalogObject::get_Name

The get_Name method provides the name of an object in the catalog.

HRESULT ICatalogObject::get_Name(

VARIANT *	retval );
Parameters

retval [out]
Pointer to the name of the object.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

E_NOTIMPL
Object has been removed from the collection.

All MTS objects have a name property. The following table provides the name property for each collection supported by the MTS Explorer:

Collection	Name Property
Packages	Name
ComponentsInPackage	ProgID
RolesInPackage	Name
RolesForPackageComponents	Name
UsersInRole	User
InterfacesForComponent	Name
InterfacesForRemoteComponent	Name
RemoteComponents	ProgID
MethodsForInterface	Name


ICatalogObject::IsPropertyReadOnly

The IsPropertyReadOnly method determines if a property is read-only.

HRESULT ICatalogObject::IsPropertyReadOnly(

BSTR	bstrPropName
VARIANT_BOOL *	retval);
Parameters

bstrPropName [in]
BSTR containing the name of the property.

retval [out]
Boolean indicating if the property is read-only.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid property name passed as a parameter. Can also indicate that an Out parameter is NULL.

Remarks

For more information about read-only property values and collections, see the Using MTS Collections topic.

See Also

IsPropertyWriteOnly


ICatalogObject::IsPropertyWriteOnly

The IsPropertyWriteOnly method indicates if a property can be written but not read.

HRESULT ICatalogObject::IsPropertyWriteOnly(

BSTR	bstrPropName
VARIANT_BOOL *	retval);
Parameters

bstrPropName [in]
BSTR containing the name of the property that may or may not be write-only.

retval [out]
Boolean indicating if the property is write-only.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Invalid property name passed as a parameter. Can also indicate that an Out parameter is NULL.

Remarks

For more information about read-only property values and collections, see the Using MTS Collections topic.

See Also

IsPropertyReadOnly


ICatalogObject::get_Valid

The get_Valid method determines if properties on an object were successfully read from the catalog.

HRESULT ICatalogObject::get_Valid(

VARIANT_BOOL *	retval);
Parameters

retval [out]
Boolean indicating if properties were successfully read. If this method returns True, all properties on an object were read from the catalog.

Return Values

S_OK
Method completed successfully.

E_INVALIDARG
Out parameter is NULL.

E_NOTIMPL
Object removed from the collection.


MTS IPackageUtil Interface

The IPackageUtil object enables a package to be installed and exported within the Packages collection. The IPackageUtil interface contains the following methods:

IPackageUtil::InstallPackage

IPackageUtil::ExportPackage

IPackageUtil::ShutdownPackage

See the Using MTS Collections topic for a list of the MTS collections and their properties.


IPackageUtil::InstallPackage

The InstallPackages method installs a pre-built package.

HRESULT IPackageUtil::InstallPackage(

BSTR	bstrPackageFile
BSTR	bstrInstallPath
long	1Options);
Parameters

bstrPackageFile [in]
BSTR containing the name of the package file to install.

bstrInstallPath [in]
BSTR containing component install path.

1Options [in]
Integer specifying export options. This method supports MtsExportUsers, which includes users in roles in the package file.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing objects and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_PDFREADFAIL
Error occurred reading the package file.

E_MTS_PDFVERSION
Package file version is invalid.

E_MTS_BADPATH
Package file path is invalid.

E_MTS_PACKAGEEXISTS
Package with the same ID is already installed.

E_MTS_ROLEEXISTS
Role with the same ID is already installed. The role ID in the package file is likely corrupted.

E_MTS_CANTCOPYFILE
Errors occurred copying one or more files to the install directory.

E_MTS_INVALIDUSERIDS
One or more user IDs for roles were invalid.

E_MTS_CLSIDORIIDMISMATCH
One or more component/interface identifiers in a component DLL do not match the identifiers saved in the package file. The package file is likely out of date.

E_MTS_PACKDIRNOTFOUND
The package install directory is invalid.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallPackage method's return values.


IPackageUtil::ExportPackage

The ExportPackage method exports a package according to its package identifier.

HRESULT IPackageUtil::ExportPackage(

BSTR	bstrPackageID
BSTR	bstrPackageFile
long	1Options);
Parameters

bstrPackageID [in]
BSTR containing the unique identifier of the package to export.

bstrPackageFile [in]
BSTR containing the name of the package file to export.

1Options [in]
Either zero (for no option selected) or MtsExportUsers, which includes users in roles in the package file.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing objects and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_PDFWRITEFAIL
Error occurred writing the package file.

E_MTS_NOTYPELIB
Could not find the type library for one or more components.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the ExportPackage method's return values.


IPackageUtil::ShutdownPackage

The ShutdownPackage method shuts down a single package, thereby terminating that application process.

HRESULT IPackageUtil::ShutdownPackage(

BSTR	bstrPackageID
Parameters

bstrPackageID [in]
BSTR containing the unique identifier of the package to shut down.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing objects and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_PDFWRITEFAIL
Error occurred writing the package file.

E_MTS_NOTYPELIB
Could not find the type library for one or more components.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.


MTS IComponentUtil Interface

The IComponentUtil object provides methods to install a component in a specific collection and to import components registered as an in-proc server. The IComponentUtil interface contains the following methods:

IComponentUtil::InstallComponent

IComponentUtil::ImportComponent

IComponentUtil::ImportComponentByName

IComponentUtil::GetCLSIDs


IComponentUtil::InstallComponent

The InstallComponent method installs a component.

HRESULT IComponentUtil::InstallComponent(

BSTR	bstrDLLFile
BSTR	bstrTypelibFile
BSTR	bstrProxyStubDLL);
Parameters

bstrDLLFile [in]
BSTR containing the name of the DLL file providing the components to install.

bstrTypelibFile [in]
BSTR containing the name of the external type library file. If the type library file is embedded in the DLL, pass in an empty string for this parameter.

bstrProxyStubDLL [in]
BSTR containing the name of the proxy-stub DLL file. If there is no proxy-stub DLL associated with the component, pass in an empty string for this parameter.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallComponent method's return values.


IComponentUtil::ImportComponent

The ImportComponent method imports a component that is already registered as an in-process (in-proc) server.

HRESULT IComponentUtil::ImportComponent(

BSTR	bstrCLSID);
Parameters

bstrCLSID [in]
BSTR containing the CLSID of the component to import.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the ImportComponent method's return values.

See Also

ImportComponentByName


IComponentUtil::ImportComponentByName

The ImportComponentByName method imports a component that is already registered as an in-process (in-proc) server. This method uses the component's programmatic identifier (ProgID) for the import procedure.

HRESULT IComponentUtil::ImportComponentByName(

BSTR	bstrProgID);
Parameters

bstrProgID [in]
BSTR containing the ProgID of the component to import.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the ImportComponentByName method's return values.

See Also

ImportComponent


IComponentUtil::GetCLSIDs

The GetCLSIDs method fills an array with the installable component CLSIDs from a DLL and/or type library.

HRESULT IComponentUtil::GetCLSIDs(

BSTR	bstrDLLFile
BSTR	bstrTypeLibFile
SAFEARRAY**	ppsaCLSIDs)
Parameters

bstrDLLFile [in]
BSTR containing the name of the DLL file providing the components to check for allowable installation.

bstrTypeLibFile [in]
BSTR containing the name of the external type library file to check for installable components.

ppsaCLSIDs [out]
Pointer to a pointer to a SAFEARRAY containing VARIANTS which contain the CLSIDs of installable components in the given DLL and/or type library.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.


MTS IRemoteComponentUtil Interface

You can use the IRemoteComponentUtil object to program your application to pull remote components from a package on a remote server. The IRemoteComponentUtil interface contains the following methods:

IRemoteComponentUtil::InstallRemoteComponent

IRemoteComponentUtil::InstallRemoteComponentByName


IRemoteComponentUtil::InstallRemoteComponent

The InstallRemoteComponent method pulls a component to install from a package on a remote server.

HRESULT IRemoteComponentUtil::InstallRemoteComponent(

BSTR	bstrServer
BSTR	bstrPackageID
BSTR	bstrCLSID);
Parameters

bstrServer [in]
BSTR containing the name of the remote server from which to pull the component to install.

PackageID [in]
BSTR containing the identifier of the package containing the remote component.

bstrCLSID [in]
BSTR containing the class identifier (CLSID) of the remote component.

Return Values

S_OK
Method returned successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallRemoteComponent method's return values.

See Also

InstallRemoteComponentByName


IRemoteComponentUtil::InstallRemoteComponentByName

The InstallRemoteComponentByName method pulls remote components from the package on a remote server and installs the component by package name and programmatic ID (ProgID).

HRESULT IRemoteComponentUtil::InstallRemoteComponentByName(

BSTR	bstrSever
BSTR	PackageName
BSTR	bstrProgID);
Parameters

bstrSever [in]
BSTR containing the name of the remote server from which to pull the component to install.

PackageName [in]
BSTR containing the name of the package containing the remote component.

bstrProgID [in]
BSTR containing the ProgID of the component to install.

Return Values

S_OK
Method completed successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing objects. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallRemoteComponentByName method's return values.

See Also

InstallRemoteComponent


MTS IRoleAssociationUtil Interface

Call methods on the IRoleAssociationUtil object to associate roles with a component or component interface. The IRoleAssociationUtil interface contains the following methods:

IRoleAssociationUtil::AssociateRole

IRoleAssociationUtil::AssociateRoleByName


IRoleAssociationUtil::AssociateRole

The AssociateRole method associates a role with a component or component interface.

HRESULT IRoleAssociationUtil::AssociateRole(
BSTR	bstrRoleID
);

Parameters

bstrRoleID [in]
BSTR containing the ID of the role to associate with a component or component interface.

Return Values

S_OK
Method returned successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing objects. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the AssociateRole method's return values.

See Also

AssociateRoleByName


IRoleAssociationUtil::AssociateRoleByName

The AssociateRoleByName method associates a role by its name with a specified component or component interface.

HRESULT IRoleAssociationUtil::AssociateRoleByName(

BSTR	bstrRoleName);
Parameters

bstrRoleName [in]
BSTR containing the name of the role to associate with a component or component interface.

Return Values

S_OK
Method returned successfully.

E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.

E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.

E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.

E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.

REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.

Remarks

Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the AssociateRoleByName method's return values.

See Also

AssociateRole


GetObjectContext (disambiguator)
GetObjectContext

Visual Basic	GetObjectContext Function

Visual C++	GetObjectContext Function

Visual J++	MTx.GetObjectContext Method

Context.getObjectContext Method


SafeRef (disambiguator)
SafeRef

Visual Basic	SafeRef Function

Visual C++	SafeRef Function

Visual J++	Context.safeRef Method

MTx.SafeRef Method


IObjectContext Interface, ObjectContext Object (disambiguator)
IObjectContext Interface, ObjectContext Object, Context Class

Visual Basic	ObjectContext Object

Visual C++	IObjectContext Interface

Visual J++	Context Class

IObjectContext Interface


SetAbort Method (disambiguator)
SetAbort Method

Visual Basic	SetAbort Method

Visual C++	IObjectContext::SetAbort Method

Visual Basic	Context.setAbort Method

IObjectContext.SetAbort Method


SetComplete Method (disambiguator)
SetComplete Method

Visual Basic	SetComplete Method

Visual C++	IObjectContext::SetComplete Method

Visual J++	Context.setComplete Method

IObjectContext.SetComplete Method


EnableCommit Method (disambiguator)
EnableCommit Method

Visual Basic	EnableCommit Method

Visual C++	IObjectContext::EnableCommit Method

Visual J++	Context.enableCommit Method

IObjectContext.EnableCommit Method


DisableCommit Method (disambiguator)
DisableCommit Method

Visual Basic	DisableCommit Method

Visual C++	IObjectContext::DisableCommit Method

Visual J++	Context.disableCommit Method

IObjectContext.DisableCommit Method


CreateInstance Method (disambiguator)
CreateInstance Method

Visual Basic	CreateInstance Method

Visual C++	IObjectContext::CreateInstance Method

Visual J++	Context.createObject Method

IObjectContext.CreateInstance Method


IsInTransaction Method (disambiguator)
IsInTransaction Method

Visual Basic	IsInTransaction Method

Visual C++	IObjectContext::IsInTransaction Method

Visual J++	Context.isInTransaction Method

IObjectContext.IsInTransaction Method


IsCallerInRole Method (disambiguator)
IsCallerInRole Method

Visual Basic	IsCallerInRole Method

Visual C++	IObjectContext::IsCallerInRole Method

Visual J++	Context.isCallerInRole Method

IObjectContext.IsCallerInRole Method


IsSecurityEnabled Method (disambiguator)
IsSecurityEnabled Method

Visual Basic	IsSecurityEnabled Method

Visual C++	IObjectContext::IsSecurityEnabled Method

Visual J++	Context.isSecurityEnabled Method

IObjectContext.IsSecurityEnabled Method


ITransactionContext Interface, TransactionContext Object (disambiguator)
ITransactionContextEx Interface, TransactionContext Object

Visual Basic	TransactionContext Object

Visual C++	ITransactionContextEx Interface

Visual J++	ITransactionContextEx Interface


Abort Method (disambiguator)
Abort Method

Visual Basic	Abort Method

Visual C++	ITransactionContextEx::Abort Method

Visual J++	ITransactionContextEx.Abort Method


Commit Method (disambiguator)
Commit Method

Visual Basic	Commit Method

Visual C++	ITransactionContextEx::Commit Method

Visual J++	ITransactionContextEx.Commit Method


IObjectControl Interface (disambiguator)
IObjectControl Interface

Visual Basic	ObjectControl Interface

Visual C++	IObjectControl Interface

Visual J++	IObjectControl Interface


Activate Method (disambiguator)
Activate Method

Visual Basic	Activate Method

Visual C++	IObjectControl::Activate Method

Visual J++	IObjectControl.Activate Method


CanBePooled Method (disambiguator)
CanBePooled Method

Visual Basic	CanBePooled Method

Visual C++	IObjectControl::CanBePooled Method

Visual J++	IObjectControl.CanBePooled Method


Deactivate Method (disambiguator)
Deactivate Method

Visual Basic	Deactivate Method

Visual C++	IObjectControl::Deactivate Method

Visual J++	IObjectControl.Deactivate Method


ISharedProperty Interface, SharedProperty Object (disambiguator)
ISharedProperty Interface, SharedProperty Object

Visual Basic	SharedProperty Object

Visual C++	ISharedProperty Interface

Visual J++	ISharedProperty Interface


Value (disambiguator)
Value

Visual Basic	Value Property

Visual C++	ISharedProperty::get_Value Method

Visual C++	ISharedProperty::put_Value Method

Visual J++	ISharedProperty.getValue Method

Visual J++	ISharedProperty.putValue Method


ISharedPropertyGroup Interface, SharedPropertyGroup Object (disambiguator)
ISharedPropertyGroup Interface, SharedPropertyGroup Object

Visual Basic	SharedPropertyGroup Object

Visual C++	ISharedPropertyGroup Interface

Visual J++	ISharedPropertyGroup Interface


CreateProperty Method (disambiguator)
CreateProperty Method

Visual Basic	CreateProperty Method

Visual C++	ISharedPropertyGroup::CreateProperty Method

Visual J++	ISharedPropertyGroup.CreateProperty Method


CreatePropertyByPosition Method (disambiguator)
CreatePropertyByPosition Method

Visual Basic	CreatePropertyByPosition Method

Visual C++	ISharedPropertyGroup::CreatePropertyByPosition Method

Visual J++	ISharedPropertyGroup.CreatePropertyByPosition Method


Property (disambiguator)
Property

Visual Basic	Property Property

Visual C++	ISharedPropertyGroup::get_Property Method

Visual J++	ISharedPropertyGroup.getProperty Method

Context.getProperty Method

Context.getPropertyNames Method


PropertyByPosition (disambiguator)
PropertyByPosition

Visual Basic	PropertyByPosition Property

Visual C++	ISharedPropertyGroup::get_PropertyByPosition Method

Visual J++	ISharedPropertyGroup.getPropertyByPosition Method


ISharedPropertyGroupManager Interface, SharedPropertyGroupManager Object (disambiguator)
ISharedPropertyGroupManager Interface, SharedPropertyGroupManager Object

Visual Basic	SharedPropertyGroupManager Object

Visual C++	ISharedPropertyGroupManager Interface

Visual J++	ISharedPropertyGroupManager Interface


CreatePropertyGroup Method (disambiguator)
CreatePropertyGroup Method

Visual Basic	CreatePropertyGroup Method

Visual C++	ISharedPropertyGroupManager::CreatePropertyGroup Method

Visual J++	ISharedPropertyGroupManager.CreatePropertyGroup Method


Group (disambiguator)
Group

Visual Basic	Group Property

Visual C++	ISharedPropertyGroupManager::get_Group Method

Visual J++	ISharedPropertyGroupManager.getGroup Method


get_NewEnum Method (disambiguator)
get_NewEnum, get__NewEnum Methods

Visual C++	ISharedPropertyGroupManager::get__NewEnum Method

Visual J++	ISharedPropertyGroupManager.get_NewEnum Method


IGetContextProperties Interface (disambiguator)
IGetContextProperties Interface

Visual C++	IGetContextProperties Interface

Visual J++	IGetContextProperties Interface


Count Method (disambiguator)
Count Method

Visual Basic	Count Method

Visual C++	Count Method

Visual J++	Count Method


EnumNames Method (disambiguator)
EnumNames Method

Visual C++	EnumNames Method

Visual J++	EnumNames Method


GetProperty Method (disambiguator)
GetProperty Method

Visual C++	GetProperty Method

Visual J++	GetProperty Method


ISecurityProperty Interface (disambiguator)
ISecurityProperty Interface

Visual Basic	SecurityProperty Object

Visual C++	ISecurityProperty Interface


GetDirectCallerName Method (disambiguator)
GetDirectCallerName Method

Visual Basic	GetDirectCallerName Method

Visual C++	GetDirectCallerSID Method

Visual J++	Context.getDirectCallerName Method


GetDirectCreatorName Method (disambiguator)
GetDirectCreatorName Method

Visual Basic	GetDirectCreatorName Method

Visual C++	GetDirectCreatorSID Method

Visual J++	Context.getDirectCreatorName Method


GetOriginalCallerName Method (disambiguator)
GetOriginalCallerName Method

Visual Basic	GetOriginalCallerName Method

Visual C++	GetOriginalCallerSID Method

Visual J++	Context.getOriginalCallerName Method


GetOriginalCreatorName Method (disambiguator)
GetOriginalCreatorName Method

Visual Basic	GetOriginalCreatorName Method

Visual C++	GetOriginalCreatorSID Method

Visual J++	Context.getOriginalCreatorName Method


Post Method, Step1 (Visual Basic)

Public Function Post(ByRef lngAccount As Long, _

    ByRef lngAmount As Long) As String

    On Error GoTo ErrorHandler

    Post = "Hello from Account!!!"

    Exit Function

' Return the error message indicating that

' an error occurred.

ErrorHandler:

    Err.Raise Err.Number, "Bank.Account.Post", _

        Err.Description

End Function


Post Method, Step2 (Visual Basic)

Public Function Post(ByVal lngAccountNo As Long, _

    ByVal lngAmount As Long) As String

    Dim strResult As String

    On Error GoTo ErrorHandler

    ' obtain the ADO environment and connection

    Dim adoConn As New ADODB.Connection

    Dim varRows As Variant

    adoConn.Open strConnect

    On Error GoTo ErrorCreateTable

    ' update the balance

    Dim strSQL As String

    strSQL = "UPDATE Account SET Balance = Balance + "_

        + Str$(lngAmount) + " WHERE AccountNo = "

        + Str$(lngAccountNo)

TryAgain:

    adoConn.Execute strSQL, varRows

    ' if anything else happens

    On Error GoTo ErrorHandler

    ' get resulting balance which may have been

    ' further updated via triggers

    strSQL = "SELECT Balance FROM Account " _

        + "WHERE AccountNo = " + Str$(lngAccountNo)

    Dim adoRS As ADODB.Recordset

    Set adoRS = adoConn.Execute(strSQL)

    If adoRS.EOF Then

        Err.Raise Number:=APP_ERROR, _

            Description:="Error. Account " _

            + Str$(lngAccountNo) + " not on file."

    End If

    Dim lngBalance As Long

    lngBalance = adoRS.Fields("Balance").Value

    ' check if account is overdrawn

    If (lngBalance) < 0 Then

        Err.Raise Number:=APP_ERROR, _

            Description:="Error. Account " _

            + Str$(lngAccountNo) _

            + " would be overdrawn by " _

            + Str$(lngBalance) + ". Balance is still "

            + Str$(lngBalance - lngAmount) + "."

    Else

        If lngAmount < 0 Then

            strResult = strResult _

                & "Debit from account "

                & lngAccountNo & ", "

        Else

            strResult = strResult _

                & "Credit to account "

                & lngAccountNo & ", "

        End If

        strResult = strResult + "balance is $"

            & Str$(lngBalance) & ". (VB)"

    End If

    ' cleanup

    Set adoRS = Nothing

    Set adoConn = Nothing

    Post = strResult

Exit Function

ErrorCreateTable:

    On Error GoTo ErrorHandler

    ' create the account table

    Dim objCreateTable As CreateTable

    Set objCreateTable = _

    GetObjectContext.CreateInstance("Bank.CreateTable")

    objCreateTable.CreateAccount

    GoTo TryAgain

ErrorHandler:

    ' cleanup

    If Not adoRS Is Nothing Then

        Set adoRS = Nothing

    End If

    If Not adoConn Is Nothing Then

        Set adoConn = Nothing

    End If

    Post = ""         ' indicate that an error occurred

    Err.Raise Err.Number, "Bank.Accout.Post", _

        Err.Description

End Function


Post Method, Step3 (Visual Basic)

Public Function Post(ByVal lngAccountNo As Long, _

    ByVal lngAmount As Long) As String

    Dim strResult As String

    On Error GoTo ErrorHandler

    ' obtain the ADO environment and connection

    Dim adoConn As New ADODB.Connection

    Dim varRows As Variant

    adoConn.Open strConnect

    On Error GoTo ErrorCreateTable

    ' update the balance

    Dim strSQL As String

    strSQL = "UPDATE Account SET Balance = Balance + "_

        + Str$(lngAmount) + " WHERE AccountNo = "

        + Str$(lngAccountNo)

TryAgain:

    adoConn.Execute strSQL, varRows

    ' if anything else happens

    On Error GoTo ErrorHandler

    ' get resulting balance which may have been

    ' further updated via triggers

    strSQL = "SELECT Balance FROM Account " _

        + "WHERE AccountNo = " + Str$(lngAccountNo)

    Dim adoRS As ADODB.Recordset

    Set adoRS = adoConn.Execute(strSQL)

    If adoRS.EOF Then

        Err.Raise Number:=APP_ERROR, _

            Description:="Error. Account " _

            + Str$(lngAccountNo) + " not on file."

    End If

    Dim lngBalance As Long

    lngBalance = adoRS.Fields("Balance").Value

    ' check if account is overdrawn

    If (lngBalance) < 0 Then

        Err.Raise Number:=APP_ERROR, _

            Description:="Error. Account " _

            + Str$(lngAccountNo) _

            + " would be overdrawn by " _

            + Str$(lngBalance) + ". Balance is still "

            + Str$(lngBalance - lngAmount) + "."

    Else

        If lngAmount < 0 Then

            strResult = strResult _

                & "Debit from account "

                & lngAccountNo & ", "

        Else

            strResult = strResult _

                & "Credit to account "

                & lngAccountNo & ", "

        End If

        strResult = strResult + "balance is $"

            & Str$(lngBalance) & ". (VB)"

    End If

    ' cleanup

    Set adoRS = Nothing

    Set adoConn = Nothing

    ' we are finished and happy

    GetObjectContext.SetComplete

    Post = strResult

Exit Function

ErrorCreateTable:

    On Error GoTo ErrorHandler

    ' create the account table

    Dim objCreateTable As CreateTable

    Set objCreateTable = _

    GetObjectContext.CreateInstance("Bank.CreateTable")

    objCreateTable.CreateAccount

    GoTo TryAgain

ErrorHandler:

    ' cleanup

    If Not adoRS Is Nothing Then

        Set adoRS = Nothing

    End If

    If Not adoConn Is Nothing Then

        Set adoConn = Nothing

    End If

    GetObjectContext.SetAbort          ' we are unhappy

    Post = ""         ' indicate that an error occurred

    Err.Raise Err.Number, "Bank.Accout.Post", _

        Err.Description

End Function


Perform Method, Step4 (Visual Basic)

Public Function Perform(ByVal lngPrimeAccount As Long,_

    ByVal lngSecondAccount As Long, ByVal lngAmount _

    As Long, ByVal lngTranType As Long) As String

    Dim strResult As String

    On Error GoTo ErrorHandler

    ' create the account object using our context

    Dim objAccount As Bank.Account

    Set objAccount = _

        GetObjectContext.CreateInstance("Bank.Account")

    If objAccount Is Nothing Then

        Err.Raise ERROR_NUMBER, _

        Description:="Could not create account object"

    End If

    ' call the post function based on the

    ' transaction type

    Select Case lngTranType

        Case 1

            strResult = objAccount.Post(lngPrimeAccount, 0 - lngAmount)

            If strResult = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult

            End If

        Case 2

            strResult = objAccount.Post(lngPrimeAccount, lngAmount)

            If strResult = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult

            End If

        Case 3

            Dim strResult1 As String, strResult2 As String

            ' do the credit

            strResult1 = objAccount.Post(lngSecondAccount, lngAmount)

            If strResult1 = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult1

            Else

                ' then do the debit

                strResult2 = objAccount.Post(lngPrimeAccount, 0 - lngAmount)

                If strResult2 = "" Then

                ' debit failed

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult2

                Else

                    strResult = strResult1 + "  " + strResult2

                End If

            End If

        Case Else

            Err.Raise ERROR_NUMBER, _

                Description:="Invalid Transaction Type"

    End Select

    ' we are finished and happy

    GetObjectContext.SetComplete

    Perform = strResult

    Exit Function

ErrorHandler:

    GetObjectContext.SetAbort          ' we are unhappy

    Perform = ""       ' indicate that an error occured

    Err.Raise Err.Number, "Bank.MoveMoney.Perform", _

        Err.Description

End Function


GetNextReceipt Method, Step5 (Visual Basic)

Public Function GetNextReceipt() As Long

    On Error GoTo ErrorHandler

    ' If Shared property does not already exist

    ' it will be initialized

    Dim spmMgr As SharedPropertyGroupManager

    Set spmMgr = CreateObject("MTxSpm.SharedPropertyGroupManager.1")

    Dim spmGroup As SharedPropertyGroup

    Dim bResult As Boolean

    Set spmGroup = _

        spmMgr.CreatePropertyGroup("Receipt", _

        LockMethod, Process, bResult)

    Dim spmPropNextReceipt As SharedProperty

    Set spmPropNextReceipt = _

        spmGroup.CreateProperty("Next", bResult)

    ' Set the initial value of the Shared Property to

    ' 0 if the Shared Property didn't already exist.

    ' This is not entirely necessary but demonstrates

    ' how to initialize a value.

    If bResult = False Then

        spmPropNextReceipt.Value = 0

    End If

    ' Get the next receipt number and update property

    spmPropNextReceipt.Value = spmPropNextReceipt.Value + 1

    ' we are finished and happy

    GetObjectContext.SetComplete

    GetNextReceipt = spmPropNextReceipt.Value

    Exit Function

ErrorHandler:

    GetObjectContext.SetAbort          ' we are unhappy

    ' indicate that an error occured

    GetNextReceipt = -1

    Err.Raise Err.Number, _

        "Bank.GetReceipt.GetNextReceipt", _

        Err.Description

End Function


Perform Method, Step5 (Visual Basic)

Public Function Perform(ByVal lngPrimeAccount As Long,_

    ByVal lngSecondAccount As Long, ByVal lngAmount _

    As Long, ByVal lngTranType As Long) As String

    Dim strResult As String

    On Error GoTo ErrorHandler

    ' create the account object using our context

    Dim objAccount As Bank.Account

    Set objAccount = _

        GetObjectContext.CreateInstance("Bank.Account")

    If objAccount Is Nothing Then

        Err.Raise ERROR_NUMBER, _

        Description:="Could not create account object"

    End If

    ' call the post function based on the

    ' transaction type

    Select Case lngTranType

        Case 1

            strResult = objAccount.Post(lngPrimeAccount, 0 - lngAmount)

            If strResult = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult

            End If

        Case 2

            strResult = objAccount.Post(lngPrimeAccount, lngAmount)

            If strResult = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult

            End If

        Case 3

            Dim strResult1 As String, strResult2 As String

            ' do the credit

            strResult1 = objAccount.Post(lngSecondAccount, lngAmount)

            If strResult1 = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult1

            Else

                ' then do the debit

                strResult2 = objAccount.Post(lngPrimeAccount, 0 - lngAmount)

                If strResult2 = "" Then

                ' debit failed

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult2

                Else

                    strResult = strResult1 + "  " + strResult2

                End If

            End If

        Case Else

            Err.Raise ERROR_NUMBER, _

                Description:="Invalid Transaction Type"

    End Select

    ' Get Receipt Number for the transaction

    Dim objReceiptNo As Bank.GetReceipt

    Dim lngReceiptNo As Long

    Set objReceiptNo = GetObjectContext.CreateInstance("Bank.GetReceipt")

    lngReceiptNo = objReceiptNo.GetNextReceipt

    If lngReceiptNo > 0 Then

        strResult = strResult & "; Receipt No: " _

            & Str$(lngReceiptNo)

    End If

    ' we are finished and happy

    GetObjectContext.SetComplete

    Perform = strResult

    Exit Function

ErrorHandler:

    GetObjectContext.SetAbort          ' we are unhappy

    Perform = ""       ' indicate that an error occured

    Err.Raise Err.Number, "Bank.MoveMoney.Perform", _

        Err.Description

End Function


StatefulPerform Method, Step6 (Visual Basic)

Public PrimeAccount As Long

Public SecondAccount As Long

Public Function StatefulPerform(ByVal lngAmount _

    As Long, ByVal lngTranType As Long) As String

    StatefulPerform = Perform(PrimeAccount, _

        SecondAccount, lngAmount, lngTranType)

End Function


Update Method, Step7 (Visual Basic)

Public Function Update() As Long

    On Error GoTo ErrorHandler

    ' get result set and then update table

    ' with new receipt number

    Dim adoConn As New ADODB.Connection

    Dim adoRsReceipt As ADODB.Recordset

    Dim lngNextReceipt As Long

    Dim strSQL As String

    strSQL = "Update Receipt set NextReceipt = NextReceipt + 100"

    adoConn.Open strConnect

    ' Assume that if there is an ado error then

    ' the receipt table does not exist

    On Error GoTo ErrorCreateTable

TryAgain:

    adoConn.Execute strSQL

    strSQL = "Select NextReceipt from Receipt"

    Set adoRsReceipt = adoConn.Execute(strSQL)

    lngNextReceipt = adoRsReceipt!NextReceipt

    Set adoConn = Nothing

    Set adoRsReceipt = Nothing

    ' we are finished and happy

    GetObjectContext.SetComplete

    Update = lngNextReceipt

    Exit Function

ErrorCreateTable:

    On Error GoTo ErrorHandler

    ' create the receipt table

    Dim objCreateTable As CreateTable

    Set objCreateTable = CreateObject("Bank.CreateTable")

    objCreateTable.CreateReceipt

    GoTo TryAgain

ErrorHandler:

    If Not adoConn Is Nothing Then

        Set adoConn = Nothing

    End If

    If Not adoRsReceipt Is Nothing Then

        Set adoRsReceipt = Nothing

    End If

    GetObjectContext.SetAbort      ' we are unhappy

    Update = -1        ' indicate that an error occured

    Err.Raise Err.Number, "Bank.UpdateReceipt.Update", Err.Description

End Function


GetNextReceipt Method, Step7 (Visual Basic)

Public Function GetNextReceipt() As Long

    On Error GoTo ErrorHandler

    ' If Shared property does not already exist

    ' it will be initialized

    Dim spmMgr As SharedPropertyGroupManager

    Set spmMgr = CreateObject("MTxSpm.SharedPropertyGroupManager.1")

    Dim spmGroup As SharedPropertyGroup

    Dim bResult As Boolean

    Set spmGroup = _

        spmMgr.CreatePropertyGroup("Receipt", _

        LockMethod, Process, bResult)

    Dim spmPropNextReceipt As SharedProperty

    Set spmPropNextReceipt = _

        spmGroup.CreateProperty("Next", bResult)

    ' Set the initial value of the Shared Property to

    ' 0 if the Shared Property didn't already exist.

    ' This is not entirely necessary but demonstrates

    ' how to initialize a value.

    If bResult = False Then

        spmPropNextReceipt.Value = 0

    End If

    Dim spmPropMaxNum As SharedProperty

    Set spmPropMaxNum = spmGroup.CreateProperty("MaxNum", bResult)

    Dim objReceiptUpdate As Bank.UpdateReceipt

    If spmPropNextReceipt.Value >= spmPropMaxNum.Value Then

        Set objReceiptUpdate = GetObjectContext.CreateInstance("Bank.UpdateReceipt")

        spmPropNextReceipt.Value = objReceiptUpdate.Update

        spmPropMaxNum.Value = spmPropNextReceipt.Value + 100

    End If

    ' Get the next receipt number and update property

    spmPropNextReceipt.Value = spmPropNextReceipt.Value + 1

    ' we are finished and happy

    GetObjectContext.SetComplete

    GetNextReceipt = spmPropNextReceipt.Value

    Exit Function

ErrorHandler:

    GetObjectContext.SetAbort          ' we are unhappy

    ' indicate that an error occured

    GetNextReceipt = -1

    Err.Raise Err.Number, "Bank.GetReceipt.GetNextReceipt", Err.Description

End Function


Perform Method, Step8 (Visual Basic)

Public Function Perform(ByVal lngPrimeAccount As Long,_

    ByVal lngSecondAccount As Long, ByVal lngAmount _

    As Long, ByVal lngTranType As Long) As String

    Dim strResult As String

    On Error GoTo ErrorHandler

    ' check for security

    If (lngAmount > 500 Or lngAmount < -500) Then

        If Not GetObjectContext.IsCallerInRole("Managers") Then

            Err.Raise Number:=APP_ERROR, _

            Description:="Need 'Managers' role for amounts over $500"

        End If

    End If

    ' create the account object using our context

    Dim objAccount As Bank.Account

    Set objAccount = _

        GetObjectContext.CreateInstance("Bank.Account")

    If objAccount Is Nothing Then

        Err.Raise ERROR_NUMBER, _

        Description:="Could not create account object"

    End If

    ' call the post function based on the

    ' transaction type

    Select Case lngTranType

        Case 1

            strResult = objAccount.Post(lngPrimeAccount, 0 - lngAmount)

            If strResult = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult

            End If

        Case 2

            strResult = objAccount.Post(lngPrimeAccount, lngAmount)

            If strResult = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult

            End If

        Case 3

            Dim strResult1 As String, strResult2 As String

            ' do the credit

            strResult1 = objAccount.Post(lngSecondAccount, lngAmount)

            If strResult1 = "" Then

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult1

            Else

                ' then do the debit

                strResult2 = objAccount.Post(lngPrimeAccount, 0 - lngAmount)

                If strResult2 = "" Then

                ' debit failed

                Err.Raise ERROR_NUMBER, _

                    Description:=strResult2

                Else

                    strResult = strResult1 + "  " + strResult2

                End If

            End If

        Case Else

            Err.Raise ERROR_NUMBER, _

                Description:="Invalid Transaction Type"

    End Select

    ' Get Receipt Number for the transaction

    Dim objReceiptNo As Bank.GetReceipt

    Dim lngReceiptNo As Long

    Set objReceiptNo = GetObjectContext.CreateInstance("Bank.GetReceipt")

    lngReceiptNo = objReceiptNo.GetNextReceipt

    If lngReceiptNo > 0 Then

        strResult = strResult & "; Receipt No: " _

            & Str$(lngReceiptNo)

    End If

    ' we are finished and happy

    GetObjectContext.SetComplete

    Perform = strResult

    Exit Function

ErrorHandler:

    GetObjectContext.SetAbort          ' we are unhappy

    Perform = ""       ' indicate that an error occured

    Err.Raise Err.Number, "Bank.MoveMoney.Perform", _

        Err.Description

End Function


Post Method, Step8 (Visual Basic)

Public Function Post(ByVal lngAccountNo As Long, _

    ByVal lngAmount As Long) As String

    Dim strResult As String

    On Error GoTo ErrorHandler

    ' check for security

    If (lngAmount > 500 Or lngAmount < -500) Then

        If Not GetObjectContext.IsCallerInRole("Managers") Then

            Err.Raise Number:=APP_ERROR, _

            Description:="Need 'Managers' role for amounts over $500"

        End If

    End If

    ' obtain the ADO environment and connection

    Dim adoConn As New ADODB.Connection

    Dim varRows As Variant

    adoConn.Open strConnect

    On Error GoTo ErrorCreateTable

    ' update the balance

    Dim strSQL As String

    strSQL = "UPDATE Account SET Balance = Balance + "_

        + Str$(lngAmount) + " WHERE AccountNo = "

        + Str$(lngAccountNo)

TryAgain:

    adoConn.Execute strSQL, varRows

    ' if anything else happens

    On Error GoTo ErrorHandler

    ' get resulting balance which may have been

    ' further updated via triggers

    strSQL = "SELECT Balance FROM Account " _

        + "WHERE AccountNo = " + Str$(lngAccountNo)

    Dim adoRS As ADODB.Recordset

    Set adoRS = adoConn.Execute(strSQL)

    If adoRS.EOF Then

        Err.Raise Number:=APP_ERROR, _

            Description:="Error. Account " _

            + Str$(lngAccountNo) + " not on file."

    End If

    Dim lngBalance As Long

    lngBalance = adoRS.Fields("Balance").Value

    ' check if account is overdrawn

    If (lngBalance) < 0 Then

        Err.Raise Number:=APP_ERROR, _

            Description:="Error. Account " _

            + Str$(lngAccountNo) _

            + " would be overdrawn by " _

            + Str$(lngBalance) + ". Balance is still "

            + Str$(lngBalance - lngAmount) + "."

    Else

        If lngAmount < 0 Then

            strResult = strResult _

                & "Debit from account "

                & lngAccountNo & ", "

        Else

            strResult = strResult _

                & "Credit to account "

                & lngAccountNo & ", "

        End If

        strResult = strResult + "balance is $"

            & Str$(lngBalance) & ". (VB)"

    End If

    ' cleanup

    Set adoRS = Nothing

    Set adoConn = Nothing

    ' we are finished and happy

    GetObjectContext.SetComplete

    Post = strResult

Exit Function

ErrorCreateTable:

    On Error GoTo ErrorHandler

    ' create the account table

    Dim objCreateTable As CreateTable

    Set objCreateTable = _

    GetObjectContext.CreateInstance("Bank.CreateTable")

    objCreateTable.CreateAccount

    GoTo TryAgain

ErrorHandler:

    ' cleanup

    If Not adoRS Is Nothing Then

        Set adoRS = Nothing

    End If

    If Not adoConn Is Nothing Then

        Set adoConn = Nothing

    End If

    GetObjectContext.SetAbort          ' we are unhappy

    Post = ""         ' indicate that an error occurred

    Err.Raise Err.Number, "Bank.Accout.Post", _

        Err.Description

End Function


新しいオブジェクトの作成

Microsoft Transaction Server エクスプローラのウィンドウにアイテムを追加します。[新規作成] コマンドで追加されるアイテムは、ウィンドウの右側に表示されているフォルダによって異なります。たとえば、[コンピュータ] フォルダを開いているときに [新規作成] をクリックすると、新しいコンピュータが追加されます。

ツール バーのショートカット：

[コンピュータ] フォルダにコンピュータを追加する方法については、「MTS サーバーの構成」を参照してください。

新しいパッケージを作成する方法については、「空の MTS パッケージを作成する」を参照してください。

新しいロールを作成する方法については、「新しい MTS ロールの追加」を参照してください。


大きいアイコン

ウィンドウの右側のアイテムを大きいアイコンで表示します。

ツール バーのショートカット：


小さいアイコン

ウィンドウの右側のアイテムを小さいアイコンで表示します。

ツール バーのショートカット：


一覧表示

ウィンドウの右側のアイテムを一覧で表示します。

ツール バーのショートカット：


プロパティ表示

現在選択されているフォルダ内のアイテムのプロパティの設定を表示します。プロパティは、Microsoft Transaction Server エクスプローラのウィンドウの右側に列形式で表示されます。

ツール バーのショートカット：

表示されるプロパティは、選択しているオブジェクトの種類によって異なります。次の表は、それぞれのフォルダごとに表示されるプロパティをまとめたものです。

フォルダ	プロパティ
コンピュータ	名前 ― コンピュータに割り当てられ、Windows NT のドメイン内で認識される名前です。ただし、Transaction Server を実行しているコンピュータは、マイ コンピュータと呼ばれます。
	タイムアウト
インストールされたパッケージ	名前 ― パッケージに割り当てた名前です。
	セキュリティ ― パッケージのセキュリティが有効になっているかどうかを示します。
	認証 ― 認証チェックのレベルです。
	シャットダウン ― アクティビティがないときに、パッケージがシャットダウンするまでの時間です。
	常に実行 ― 非アクティブのときでもパッケージがシャットダウンしないことを示します。
	アカウント ― パッケージ ID に設定された Windows NT アカウントです。
	パッケージ ID ― パッケージに割り当てられた汎用一意識別子 (UUID) です。
コンポーネント	Prog ID ― コンポーネントに割り当てられた名前です。
	トランザクション ― コンポーネントがトランザクションをサポートしているかどうかを示します。
	DLL
	CLSID
	MTX 使用 ― コンポーネントが Transaction Server 環境で実行されているかどうかを示します。
	イン プロセス ― コンポーネントが別のサーバー プロセスで実行されていることを示します。
	ローカル ― コンポーネントがローカル コンピュータのサーバー プロセスで実行されていることを示します
	リモート ― コンポーネントがリモート コンピュータのサーバー プロセスで実行されていることを示します。
	サーバー ― コンポーネントが実行されているリモート コンピュータの名前です。
	スレッド ― コンポーネントのスレッド モデルです。
	セキュリティ ― コンポーネントのセキュリティが有効になっているかどうかを示します。
ロール	名前 ― ロールに割り当てられた名前です。
	ロール ID ― ロールに割り当てられた一意の識別子です。
インターフェイス	名前 ― インターフェイスに割り当てられた名前です。
	インターフェイス ID ― インターフェイスに割り当てられた一意の識別子です。
	プロキシ DLL
	TypeLib ファイル ― タイプ ライブラリを含むファイルの名前です。
メソッド	名前 ― メソッドに割り当てられた名前です。
ロール メンバーシップ	名前 ― コンポーネントまたはインターフェイスに追加されたロールに、割り当てられた名前です。
	ロール ID ― ロールに割り当てられた一意の識別子です。


状態表示

コンポーネントまたはコンピュータの現在の状態を表示します。

ツール バーのショートカット：

コンピュータの状態

•	[名前] ― コンピュータに割り当てられた名前です。

•	[DTC] ― MS DTC が起動されているかどうかを示します。

コンポーネントの状態

•	[Prog ID] ― コンポーネントに割り当てられた名前です。

•	[オブジェクト] ― サーバー プロセス内に割り当てられたオブジェクトの総数です。

•	[アクティブ化] ― クライアントが使用しているオブジェクトの総数です。

•	[呼び出し中] ― 現在クライアント呼び出しを実行しているオブジェクトの総数です。


最新の情報に更新

Microsoft Transaction Server エクスプローラのウィンドウの右側に表示される情報を手作業で更新します。

ツール バーのショートカット：


用語集 (Microsoft Transaction Server)
用語集

2 フェーズ コミット

ACID

ActiveX

COM (コンポーネント オブジェクト モデル)

DCOM

ID

Microsoft Transaction Server エクスプローラ

Microsoft Transaction Server オブジェクト

Microsoft Transaction Server コンポーネント

Microsoft 分散トランザクション コーディネータ (MS DTC)

Null

ODBC リソース ディスペンサ

OLE トランザクション

XA プロトコル

アクティビティ

アパートメント スレッド

アプリケーション実行可能ファイル ユーティリティ

安全な参照

一貫性 (consistency)

イン ダウトのトランザクション

インスタンス

インターフェイス

インプロセス コンポーネント

オープン データベース コネクティビティ (ODBC)

オブジェクト

オブジェクト変数

カタログ

管理者

既成のパッケージ

共有プロパティ

クライアント

クライアント/サーバー

クラス

クラス ID (CLSID)

クラス ファクトリ

クラスタ

グループ

グローバル アカウント

原子性 (atomicity)

コンストラクタ

コンテキスト

コンテキスト オブジェクト プロパティ

コンポーネント

サーバー パッケージ

サーバー プロセス

最初の作成元

最初の呼び出し元

作成元

持続性 (durability)

自動トランザクション

ジャストインタイム アクティベーション

集成

障害の分離

スタブ

ステートフル オブジェクト

ステートレス オブジェクト

スナップイン

スレッド

セキュリティ ID (SID)

セマフォ

宣言によるセキュリティ

ダイナミック リンク ライブラリ (DLL)

タイプ ライブラリ

対話型ログオン ユーザー

直接の作成元

直接の呼び出し元

データ ソース名 (DSN)

デッドロック

同時実行

ドメイン

トランザクション

トランザクション コンテキスト

トランザクション タイムアウト

トランザクション マネージャ

トレース メッセージ

認証

パッケージ

パッケージ ファイル

ビジネス ルール

プーリング

ブール値 (Boolean)

フェイルファースト

フォールト トレランス

負荷のバランス

プロキシ

プログラム ID (progID)

プログラムによるセキュリティ

プロセスの分離

プロセス外コンポーネント

分離性 (isolation)

ベース クライアント

ベース プロセス

マーシャリング

メイン スレッド

メソッド

文字列式

ユーザー名

呼び出し元

ライブラリ パッケージ

リソース ディスペンサ マネージャ

リソース ディスペンサ

リソース マネージャ

リモート コンポーネント

リモート プロシージャ コール (RPC)

例外

レプリケーション

ローカル アカウント

ロール


ACID

トランザクションの基本的なプロパティ。原子性 (atomicity)、一貫性 (consistency)、分離性 (isolation) および持続性 (durability) をいいます。


ActiveX

ソフトウェア コンポーネントどうしが、そのコンポーネントの開発に使われた言語とは無関係に、ネットワーク環境でやりとりできるようにするための一連のテクノロジ。ActiveX はコンポーネント オブジェクト モデル (COM) を基本に作られています。


アクティビティ

単独の分散論理実行スレッドを持つ Microsoft Transaction Server オブジェクトの集合。どの Microsoft Transaction Server オブジェクトも、あるアクティビティに属しています。


管理者

Microsoft Transaction Server エクスプローラを使って Microsoft Transaction Server のコンポーネントとパッケージのインストール、構成、および管理を行うユーザー。


集成

コンポーネント オブジェクトを実装するためのコンポジション テクニック。このテクニックにより、新しいオブジェクトを作成するときに、そのオブジェクトに必要なインターフェイスをサポートする既存のオブジェクトを使うことができます。


アパートメント スレッド

"アパートメント スレッド" として構成されたコンポーネントのオブジェクトへの呼び出しに使うスレッド。各オブジェクトは、そのオブジェクトの有効期間中、アパートメント (スレッド) の中で動作します。このオブジェクトへの呼び出しは、すべてアパートメント スレッドで実行されます。たとえば、オブジェクトの状態をスレッド ローカル格納領域 (TLS) に保持するコンポーネントを実装する場合、このスレッド モデルが使われます。コンポーネントのオブジェクトは、1 つまたは複数のアパートメントに分散できます。メイン スレッドも参照してください。


アプリケーション実行可能ファイル ユーティリティ

パッケージのエクスポートによってアプリケーションの実行可能ファイルを作成できるようにする MTS エクスプローラの機能。


原子性 (atomicity)

トランザクションのすべての処理が実行されるか、またはどの処理も実行されないかのどちらかを示すトランザクションの機能。


認証

システムにアクセスしようとするユーザーの ID を確認する処理。たとえば、ユーザーの認証には一般にパスワードが使われます。


自動トランザクション

コンポーネントのオブジェクト用に、Microsoft Transaction Server ランタイム環境が、そのコンポーネントのトランザクション属性に基づいて作成するトランザクション。


ブール値 (Boolean)

True (真) または False (偽) の値、あるいは yes または no の値。


ベース クライアント

Microsoft Transaction Server ランタイム環境の外部で動作し、Microsoft Transaction Server オブジェクトのインスタンスを生成するクライアント。


ベース プロセス

ベース クライアントが実行されるアプリケーション プロセス。ベース クライアントは Microsoft Transaction Server ランタイム環境の外部で動作し、Microsoft Transaction Server オブジェクトのインスタンスを生成します。


ビジネス ルール

企業内の業務処理を定めた原則。入力規則を使用した編集、ログオンの確認、データベースの照合、方針、アルゴリズム変換などの組み合わせです。"ビジネス ロジック" とも呼ばれます。


呼び出し元

オブジェクトのメソッドを呼び出すクライアント。オブジェクトの呼び出し元は、必ずしもオブジェクトの作成元ではありません。たとえば、クライアント A がオブジェクト X を作成し、オブジェクト参照をクライアント B に渡すと、クライアント B はその参照を使ってオブジェクト X のメソッドを呼び出すことができます。この場合、クライアント A が作成元で、クライアント B が呼び出し元になります。作成元も参照してください。


カタログ

コンポーネント、パッケージ、およびロールの構成情報を保持する Microsoft Transaction Server データの格納場所。カタログを管理するには、Microsoft Transaction Server エクスプローラを使います。


クラス

特定の種類のオブジェクトのインターフェイスを定義する型。クラスはオブジェクトのプロパティと、オブジェクトの動作を制御するためのメソッドを定義します。


クラス ファクトリ

IClassFactory インターフェイスを実装するオブジェクト。このインターフェイスを使って特定のクラスのオブジェクトを作成できます。


クラス ID (CLSID)

COM コンポーネントを識別するための汎用一意識別子 (UUID)。各 COM コンポーネントの CLSID は Windows レジストリに登録され、ほかのアプリケーションからロードできるようになっています。


クライアント

ほかのプロセスまたはコンポーネントにサービスを要求するアプリケーションやプロセス。


クライアント/サーバー

クライアント アプリケーションがサーバー アプリケーションにサービスを要求するような分散アプリケーション モデル。サーバーは同時に多くのクライアントを持つことができ、クライアントは複数のサーバーにデータを要求できます。アプリケーションは、クライアントにもサーバーにもなりえます。


クラスタ

Microsoft Cluster Server を使って単一のシステムとしてアドレス指定され、管理される 2 つ以上の独立したコンピュータ システム。


COM (コンポーネント オブジェクト モデル)

オブジェクト指向テクノロジに基づいたクライアント/サーバー アプリケーションを、異なるプラットフォーム上で開発するためのオープン アーキテクチャ。クライアントは、オブジェクトに実装されたインターフェイスを通じてオブジェクトにアクセスします。COM は言語に依存しないため、ActiveX コンポーネントを作成できる言語であれば、COM アプリケーションも作成できます。


コンポーネント

ActiveX テクノロジに基づいて作成されたコードの単位。明確な仕様を持つ一連のサービスを、明確に規定されたインターフェイスを通じて提供します。コンポーネントは、実行時にクライアントが要求するオブジェクトを提供します。


同時実行

複数の処理を交互に実行することにより、プロセスやトランザクションが同時に実行されるように見えること。


一貫性 (consistency)

持続的なデータが、そのデータを変更したビジネス ルールが求める状態に一致している状態。


コンストラクタ

C++ および Java で、クラスのインスタンスが宣言されるたびに自動的に呼び出される特殊な初期化関数。この関数は、初期化されていないオブジェクトを使ったために生じるエラーを防止します。コンストラクタはクラス自体と同じ名前を持ち、値を返すことはできません。


コンテキスト

所定の Microsoft Transaction Server オブジェクトに暗黙的に関連付けられている状態。コンテキストには、オブジェクトの作成元の ID など、オブジェクトの実行環境に関する情報が含まれます。また、オブジェクトの作業を遂行するトランザクションがコンテキストに含まれることもあります。オブジェクト コンテキストは、概念的にはオペレーティング システムがプログラムの実行のために保持するプロセス コンテキストに似ています。Microsoft Transaction Server ランタイム環境が、各オブジェクトのコンテキストを管理します。


コンテキスト オブジェクト プロパティ

Internet Information Server 固有のオブジェクトなどのコンテキスト オブジェクトから取得できるプロパティ。


作成元

コンポーネントから提供されるオブジェクトを (CreateObject、CoCreateInstance、または CreateInstance メソッドを使って) 作成するクライアント。クライアントが作成したオブジェクトには、そのオブジェクトのメソッドを呼び出すためのオブジェクト参照が与えられます。呼び出し元も参照してください。


データ ソース名 (DSN)

アプリケーションが ODBC データ ソースへの接続を要求するときに使う名前。


デッドロック

2 つ以上のスレッドが永続的にブロックされている (待機している) 状態。各スレッドは、ブロックされたほかのスレッドの 1 つが排他的に保持しているリソースを待っています。たとえば、スレッド A がレコード 1 をロックしながらレコード 2 をロックするために待機しているときに、スレッド B がレコード 2 をロックしながらレコード 1 をロックするために待機している場合、2 つのスレッドはデッドロック状態になります。


宣言によるセキュリティ

Microsoft Transaction Server エクスプローラを使って構成するセキュリティ。ロールを定義することによって、パッケージ、コンポーネント、およびインターフェイスへのアクセスを制御します。ロールにより、どのユーザーがコンポーネントのインターフェイスを呼び出すことができるかを設定します。プログラムによるセキュリティも参照してください。


直接の呼び出し元

現在のサーバー プロセスを呼び出しているプロセス (ベース クライアントまたはサーバー プロセス) の ID。


直接の作成元

現在のオブジェクトを直接作成したプロセス (ベース クライアントまたはサーバー プロセス) の ID。


DCOM

ActiveX コンポーネントどうしがネットワークを介して直接通信できるようにするためのオブジェクト プロトコル。DCOM は言語に依存しないので、ActiveX コンポーネントを作成できる言語であれば、DCOM アプリケーションも作成できます。


ドメイン

Windows NT において、Windows NT サーバー ネットワークの管理者が定義し、共通のディレクトリ データベースを共有するコンピュータの集合。ドメインでは、ドメイン管理者が集中管理するユーザー アカウントとグループ アカウントにアクセスできます。各ドメインには一意の名前が付いています。


持続性 (durability)

障害が発生しても保持される状態。


ダイナミック リンク ライブラリ (DLL)

関数を使用するプロセスから独立してコンパイル、リンク、および格納される 1 つまたは複数の関数を含むファイル。オペレーティング システムは、呼び出しプロセスの起動時または実行時に、DLL をそのプロセスのアドレス空間に割り当てます。


例外

プログラムの実行中に発生し、通常の制御フローの外側でソフトウェアを実行しようとする異常な状態またはエラー。


フェイルファースト

障害の封じ込めを容易にするための Microsoft Transaction Server の原則。Transaction Server で予期しない内部エラー状態が発生すると、直ちにプロセスが強制終了され、障害に関する詳細が Windows NT のイベント ログに記録されます。


障害の分離

障害をシステムのほかのコンポーネントに拡散せず、障害の影響をコンポーネント内に抑えること。


フォールト トレランス

エラー、障害、または環境状態の変化 (停電など) から復旧するためのシステム機能。本来、フォールト トレランスでは、ユーザーの作業やファイルに影響を及ぼすことなく、完全に自動で復旧が行われます。これに対して手作業による方法では、バックアップ ファイルからデータを復元するなどの作業が必要になります。


グローバル アカウント

ユーザーのホーム ドメインの通常のユーザー アカウント。既定の設定では、ほとんどのアカウントが、グローバル アカウントに設定されています。複数のドメインが利用できる場合は、ネットワーク上の各ユーザーが 1 つのドメインだけにグローバル アカウントを 1 つだけ持つようにするのが理想的です。


グループ

1 つ以上の Windows NT ユーザー アカウントの集まりを識別する名前。


ID

パッケージにアクセスできるユーザー アカウントを指定するパッケージ プロパティ。Windows NT ドメインの特定のユーザー アカウントまたはユーザーのグループを指定できます。


イン ダウトのトランザクション

トランザクションを調整するサーバーが利用できないために、準備が整っていても、コミットするかアボートするかの判断が下されていないトランザクション。


インプロセス コンポーネント

クライアントのプロセス空間で動作するコンポーネント。通常は、ダイナミック リンク ライブラリ (DLL) になります。


インスタンス

特定のコンポーネント クラスのオブジェクト。各インスタンスには、独自のプライベートなデータ要素やメンバ変数があります。コンポーネント インスタンスは、オブジェクトと同じものを意味します。


対話型ログオン ユーザー

現在、Microsoft Transaction Server コンピュータにログオンしているユーザー。


インターフェイス

論理的に関連している操作またはメソッドのグループで、コンポーネント オブジェクトへのアクセスを提供します。


分離性 (isolation)

並行して実行されている 2 つのトランザクションが、同時実行されていないように見せかける特性。この特性によって、システムが一度に 1 つのトランザクションだけを実行しているように見えます。


ジャストインタイム アクティベーション

クライアントからの要求を実行するのに必要なときだけ Microsoft Transaction Server オブジェクトをアクティブ化できる機能。クライアントがオブジェクトへの参照を保持している間もそのオブジェクトを非アクティブ化できるため、アイドル状態のサーバー リソースをより効率的に利用できます。


ライブラリ パッケージ

パッケージを作成するクライアントのプロセス内で実行されるパッケージ。ライブラリ パッケージは、コンポーネントの追跡、ロールのチェック、プロセスの分離をサポートしません。MTS は、ライブラリ パッケージとサーバー パッケージの 2 種類のパッケージをサポートします。


負荷のバランス

ネットワーク作業による処理の負荷を複数のサーバーに分散し、ネットワーク全体のパフォーマンスを向上させること。


ローカル アカウント

信頼される側のドメインに通常使うアカウントを持たないユーザーのために、ローカル ドメインで与えられるアカウント。ローカル アカウントは対話型ログオンに使うことはできません。1 つのドメインで作成されたローカル アカウントは、信頼される側のドメインでは使用できません。


メイン スレッド

"シングル スレッド" として指定されたコンポーネントのすべてのオブジェクトを実行するときに使用される単一のスレッド。アパートメント スレッドも参照してください。


マーシャリング

インターフェイス メソッドのパラメータを、スレッドやプロセスの境界を越えてパッケージ化して送る処理。


メソッド

オブジェクトに対して作用するプロシージャ (関数)。


Microsoft 分散トランザクション コーディネータ (MS DTC)

複数のリソース マネージャにまたがるトランザクションを調整するトランザクション マネージャ。複数のコンピュータ上に存在する可能性のある複数のリソース マネージャに処理がまたがる場合でも、その処理を 1 つのアトミック トランザクションとしてコミットできます。


Microsoft Transaction Server コンポーネント

Microsoft Transaction Server ランタイム環境で実行される COM コンポーネント。Transaction Server コンポーネントは、ダイナミック リンク ライブラリ (DLL) で、オブジェクトを作成するためのクラス ファクトリを実装し、コンポーネントのインターフェイスのすべてが標準マーシャリングのためにタイプ ライブラリに記述されている必要があります。


Microsoft Transaction Server エクスプローラ

Microsoft Transaction Server コンポーネントを分散コンピュータ ネットワークで構成し、管理するためのアプリケーション。


Microsoft Transaction Server オブジェクト

Microsoft Transaction Server ランタイム環境で実行される COM オブジェクトで、Transaction Server プログラミング モデルと配置モデルに準拠するものです。


Null

データがないこと、または不明であることを示す値。


オブジェクト

COM コンポーネントのランタイム インスタンス。オブジェクトはコンポーネントのクラス ファクトリによって作成されます。オブジェクトはインスタンスと同じものを意味します。


オブジェクト変数

オブジェクトへの参照を含む変数。


ODBC リソース ディスペンサ

標準 ODBC プログラミング インターフェイスを使用する Microsoft Transaction Server コンポーネントのデータベース接続のプールを管理するリソース ディスペンサ。


OLE トランザクション

コンポーネント オブジェクト モデル (COM) に基づくオブジェクト指向の 2 フェーズ コミット プロトコル。Microsoft 分散トランザクション コーディネータ (DTC) によって調整される分散トランザクションに参加するためにリソース マネージャが使用します。


オープン データベース コネクティビティ (ODBC)

さまざまなデータ ソースに接続するときに使う標準プログラミング言語インターフェイス。


最初の呼び出し元

処理を開始したベース クライアントの ID。


最初の作成元

現在のオブジェクトを作成したベース クライアントの ID。最初の作成元がオブジェクトをほかのベース クライアントに渡した場合だけ、最初の呼び出し元と最初の作成元が別になります。最初の呼び出し元も参照してください。


プロセス外コンポーネント

コンポーネントのクライアントとは別のプロセス空間で動作するコンポーネント。Microsoft Transaction Server では、コンポーネントを代理サーバー プロセスにロードすることにより、DLL として実装されているコンポーネントをクライアントのプロセスの外部で使用できます。


パッケージ

関連するアプリケーション機能を実行する 1 組のコンポーネント。パッケージ内のすべてのコンポーネントは、同じ Microsoft Transaction Server サーバー プロセスで動作します。パッケージは、セキュリティ情報がいつ確認されるかを定義する信頼境界であり、1 組のコンポーネントの配置単位でもあります。パッケージを作成するには、Transaction Server エクスプローラを使います。パッケージは、ライブラリ パッケージまたはサーバー パッケージのいずれかです。


パッケージ ファイル

パッケージのロールとコンポーネントに関する情報が格納されているファイル。パッケージ ファイルを作成するには、Transaction Server エクスプローラのパッケージ エクスポート機能を使います。既成のパッケージを作成すると、関連するコンポーネント ファイル (DLL、タイプ ライブラリ、および実装されていればプロキシ/スタブ DLL) が、作成されたパッケージ ファイルと同じディレクトリにコピーされます。


プーリング

オブジェクト、データベース接続など、既に割り当てられたリソースの集合を利用してパフォーマンスを最適化すること。プーリングにより、リソース割り当てをより効率的に行うことができます。


既成のパッケージ

パッケージのロールとコンポーネントに関する情報が格納されているパッケージ ファイル。パッケージ ファイルを作成するには、Transaction Server エクスプローラのパッケージ エクスポート機能を使います。既成のパッケージを作成すると、関連するコンポーネント ファイル (DLL、タイプ ライブラリ、および実装されていればプロキシ/スタブ DLL) が、作成されたパッケージ ファイルと同じディレクトリにコピーされます。


プロセスの分離

あるサーバー プロセスをほかのサーバー プロセスから分離するために、別のメモリ領域で実行する方法。プロセスの分離によって、サーバー プロセスはほかのアプリケーションの致命的なエラーから保護されます。また、サーバー プロセスを分離することにより、分離されたプロセスがアプリケーションの致命的なエラーによってほかのサーバー プロセスを終了させることも防止できます。プロセスの分離をサポートする MTS パッケージは、サーバー パッケージと呼ばれます。


プログラム ID (progID)

COM コンポーネントを識別する名前。たとえば、Bank.MoveMoney をプログラム ID にすることができます。


プログラムによるセキュリティ

コンポーネントにより提供される手続きによるロジックで、要求された操作を実行する権限がクライアントにあるかどうかを判断します。宣言によるセキュリティも参照してください。


プロキシ

異なるスレッドや異なるプロセスなど、異なる実行環境で実行されているアプリケーション オブジェクトを呼び出すためにクライアントが必要とするパラメータ マーシャリングや通信を行うインターフェイス固有のオブジェクト。プロキシは、クライアントと同じ場所にあり、対応するスタブと通信します。対応するスタブは、呼び出されているアプリケーション オブジェクトと同じ場所にあります。


リモート コンポーネント

異なるコンピュータ上のクライアントが利用するコンポーネント。


リモート プロシージャ コール (RPC)

あるプロセスから別のプロセスで実行されている機能を呼び出すための規格。プロセスは同じコンピュータ上にあっても、ネットワーク上の異なるコンピュータ上にあってもかまいません。


レプリケーション

あるコンピュータから別のコンピュータにカタログをコピーする操作。レプリケーションは、クラスタ化された複数の MTS サーバーを同期化するために使います。


リソース ディスペンサ

プロセス内の持続性のないリソースの同期と管理を行い、Microsoft Transaction Server オブジェクトが簡単に、しかも効率よくリソースを共有できるようにするためのサービス。たとえば、ODBC リソース ディスペンサはデータベース接続のプールを管理します。


リソース ディスペンサ マネージャ

リソース ディスペンサの集合の内部で処理を調整するダイナミック リンク ライブラリ (DLL)。


リソース マネージャ

持続的なデータを管理するシステム サービス。サーバー アプリケーションは、リソース マネージャを使って、手持ちの在庫、受注残り、売掛金のレコードなどのアプリケーションの持続的な状態を保持します。リソース マネージャはトランザクション マネージャと協調して動作し、アプリケーションに対して (2 フェーズ コミット プロトコルを使って) 原子性 (atomicity) と分離性 (isolation) を保証します。Microsoft SQL Server はリソース マネージャの一例です。


ロール

一連のコンポーネントのユーザーの分類を定義するシンボル名。各ロールには、どのユーザーがコンポーネントのインターフェイスを呼び出すことができるかが定義されています。


安全な参照

現在のオブジェクトのコンテキストの外部に渡しても安全な、現在のオブジェクトへの参照。


セキュリティ ID (SID)

セキュリティ システムにログオンしたユーザーを識別するための一意の名前。セキュリティ ID (SID) で 1 人のユーザーを識別する場合も、ユーザーのグループを識別する場合もあります。


セマフォ

リソース マネージャやリソース ディスペンサの内部で使用されるロック機構。セマフォにはシンボル名がなく、共有モードと排他モードでだけアクセスされます。また、デッドロックは検出されず、自動的な解放やコミットもありません。


サーバー パッケージ

ローカル コンピュータ上のパッケージ独自のプロセス内で分離されて実行されるパッケージ。サーバー パッケージは、ロールに基づくセキュリティ、リソースの共有、プロセスの分離、および (パッケージの追跡などの) プロセス管理をサポートします。MTS は、ライブラリ パッケージとサーバー パッケージの 2 種類のパッケージをサポートします。


サーバー プロセス

Microsoft Transaction Server コンポーネントのホストとなるプロセス。Microsoft Transaction Server コンポーネントは、クライアントのコンピュータの代理サーバー プロセス、またはクライアント アプリケーション プロセスのいずれかにロードすることができます。


共有プロパティ

同一サーバー プロセス内のすべてのオブジェクトから共有プロパティ マネージャを介して利用できる変数。共有プロパティには、バリアント型で表すことのできるあらゆる型の値を保持することができます。


スナップイン

Microsoft Management Console (MMC) がホストとなる管理プログラム。Windows NT 上の MTS エクスプローラはスナップインです。


ステートフル オブジェクト

1 つ以上のクライアントからの呼び出しにより蓄積されたプライベートな状態を保持するオブジェクト。


ステートレス オブジェクト

1 つ以上のクライアントからの呼び出しにより蓄積されたプライベートな状態を保持しないオブジェクト。


文字列式

文字が連続して並び、文字列として評価できる式。


スタブ

異なるスレッドや異なるプロセスなど、異なる実行環境で実行されているクライアントからの呼び出しを受けるためにアプリケーション オブジェクトが必要とするパラメータ マーシャリングや通信を行うインターフェイス固有のオブジェクト。スタブはアプリケーション オブジェクトと同じ場所にあり、アプリケーション オブジェクトを呼び出しているクライアントと同じ場所にある、対応するプロキシと通信します。


スレッド

オペレーティング システムが CPU 時間を割り当てる基本単位。スレッドは、現在別のスレッドが実行している部分を含め、アプリケーションのコードのどの部分でも実行できます。1 つのプロセスのすべてのスレッドは、そのプロセスの仮想アドレス空間、グローバル変数、およびオペレーティング システムのリソースを共有しています。


トランザクション

アトミックな処理として実行される作業単位。つまり、処理は全体として成功するか、または失敗するかのどちらかです。


トランザクション コンテキスト

クライアントが 1 つのトランザクションに 1 つ以上のオブジェクトを動的に組み込むことができるようにするためのオブジェクト。


トランザクション マネージャ

原子性 (atomicity) を実現するために、トランザクションの結果を調整する役割を果たすシステム サービス。トランザクション マネージャにより、リソース マネージャはトランザクションをコミットするかアボートするかについて、一貫した判断を下すことができます。


トレース メッセージ

スタートアップ、シャットダウンなど、Microsoft Transaction Server のさまざまなアクティビティの現在の状態が記述されたメッセージ。


トランザクション タイムアウト

トランザクション マネージャによって自動的にアボートされるまで、トランザクションがアクティブな状態を維持できる時間の上限。


タイプ ライブラリ

ActiveX テクノロジを使ってオブジェクトを公開するためのデータ型、モジュール、およびインターフェイスの標準的な記述を含むファイル。


2 フェーズ コミット

複数のサーバーに適用されるトランザクションが、確実にすべてのサーバーで完了するか、またはまったく処理されないようにするためのプロトコル。2 フェーズ コミットは、トランザクション マネージャによって調整され、リソース マネージャによってサポートされます。


ユーザー名

Windows NT のユーザー アカウントを識別する名前。


XA プロトコル

X/Open DTP グループによって定義された 2 フェーズ コミット プロトコル。Informix、Oracle、および DB2 など、多くの UNIX データベースはネイティブで XA をサポートします。