Caché Direct の使用法 - InterSystems

Caché Direct の使用法
Version 2013.1
2013 年 07 月 02 日
InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com
Caché Direct の使用法
Caché Version 2013.1 2013 年 07 月 02 日
Copyright © 2012 InterSystems Corporation
All rights reserved.
このドキュメントは、 Sun Microsystems、RenderX Inc.、アドビシステムズおよびワールドワイド・ウェブ・コンソーシアム（www.w3c.org）のツールと
情報を使用して、 Adobe Portable Document Format (PDF)で作成およびフォーマットされました。主要ドキュメント開発ツールは、InterSystemsが構
築したCacheéと Javaを使用した特別目的のXML処理アプリケーションです。
,
,
Caché WEBLINK, Distributed Cache Protocol, M/SQL, M/NET および M/PACT は InterSystems Corporation の登録商標です。
,
,
and
,
InterSystems TrakCare, InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP および InterSystems Zen は InterSystems Corporation の
登録商標です。
ここで使われている他の全てのブランドまたは製品名は、各社および各組織の商標または登録商標です。
このドキュメントは、インターシステムズ社(住所：One Memorial Drive, Cambridge, MA 02142)あるいはその子会社が所有する企業秘密および秘密
情報を含んでおり、インターシステムズ社の製品を稼動および維持するためにのみ提供される。この発行物のいかなる部分も他の目的のために使
用してはならない。また、インターシステムズ社の書面による事前の同意がない限り、本発行物を、いかなる形式、いかなる手段で、その全てまたは
一部を、再発行、複製、開示、送付、検索可能なシステムへの保存、あるいは人またはコンピュータ言語への翻訳はしてはならない。
かかるプログラムと関連ドキュメントについて書かれているインターシステムズ社の標準ライセンス契約に記載されている範囲を除き、ここに記載さ
れた本ドキュメントとソフトウェアプログラムの複製、使用、廃棄は禁じられている。インターシステムズ社は、ソフトウェアライセンス契約に記載され
ている事項以外にかかるソフトウェアプログラムに関する説明と保証をするものではない。さらに、かかるソフトウェアに関する、あるいはかかるソフ
トウェアの使用から起こるいかなる損失、損害に対するインターシステムズ社の責任は、ソフトウェアライセンス契約にある事項に制限される。
前述は、そのコンピュータソフトウェアの使用およびそれによって起こるインターシステムズ社の責任の範囲、制限に関する一般的な概略である。完
全な参照情報は、インターシステムズ社の標準ライセンス契約に記され、そのコピーは要望によって入手することができる。
インターシステムズ社は、本ドキュメントにある誤りに対する責任を放棄する。また、インターシステムズ社は、独自の裁量にて事前通知なしに、本ド
キュメントに記載された製品および実行に対する代替と変更を行う権利を有する。
インターシステムズ社の製品に関するサポートやご質問は、以下にお問い合わせください：
Tel:
Fax:
Email:
InterSystems Worldwide Customer Support
+1 617 621-0700
+1 617 374-9391
[email protected]
目次
このドキュメントについて ................................................................................................... 1
1 Caché Direct 入門 ........................................................................................................ 3
1.1 概念 .................................................................................................................. 3
1.1.1 用語 .......................................................................................................... 4
1.1.2 コミュニケーション・モデル ............................................................................. 5
1.2 使用可能なツールと方法 ....................................................................................... 5
2 VisM コントロールの使用に関する基本 ............................................................................ 7
2.1 VisM コントロールへのアクセス ............................................................................... 7
2.2 接続と切断 ......................................................................................................... 8
2.2.1 接続文字列と接続タグ ................................................................................. 8
2.2.2 Caché への接続 .......................................................................................... 9
2.2.3 CDConnect のチャネルの変更 ..................................................................... 10
2.2.4 Caché からの切断 ...................................................................................... 10
2.2.5 CDConnect の破棄 .................................................................................... 10
2.2.6 方法の概要 .............................................................................................. 10
2.3 ネームスペースの設定 ........................................................................................ 12
2.4 コードの実行 ..................................................................................................... 13
2.5 ミラーリングされたプロパティの使用 ....................................................................... 13
2.5.1 ミラーリングされた基本的な値の使用 ............................................................. 14
2.5.2 PLIST の使用 ........................................................................................... 14
2.6 Visual Basic ユーザ・インタフェースへのコールバック ................................................ 15
2.6.1 Visual Basic コールバックをサポートするための要件 ........................................ 16
2.6.2 コントロールのプロパティの参照 ................................................................... 16
2.6.3 コントロールのメソッドの実行 ........................................................................ 16
2.7 Windows 関数や Caché ユーティリティ機能の使用 ................................................... 16
2.8 メッセージ制約の理解 ......................................................................................... 17
2.8.1 Unicode とロケールの問題 ........................................................................... 17
2.8.2 メッセージのサイズ ..................................................................................... 18
2.9 例 .................................................................................................................... 18
2.9.1 簡単な例： Lightweight Caché ターミナル ...................................................... 18
2.9.2 その他の例 ............................................................................................... 19
3 その他の機能 ............................................................................................................. 21
3.1 概要 ................................................................................................................. 21
3.2 エラー・トラップ ................................................................................................... 22
3.2.1 %cdEHOOK ローカル変数 ........................................................................... 22
3.3 キープ・アライブ機能 ........................................................................................... 22
3.3.1 初期のキープ・アライブ間隔 ........................................................................ 23
3.3.2 キープ・アライブ設定 (クライアント) ................................................................ 23
3.3.3 キープ・アライブ・エラーのシャットダウン・イベント (クライアント) .......................... 23
3.4 サーバの読み取りループと終了確認 ..................................................................... 24
3.4.1 サーバの終了確認手順 .............................................................................. 24
3.4.2 %cdPULSE ローカル変数 ............................................................................. 24
3.5 フックの読み取りと書き込み .................................................................................. 25
3.5.1 サーバ側の読み取りフックと書き込みフック ..................................................... 25
3.5.2 クライアント側の読み取りフックと書き込みフック ............................................... 25
3.6 その他のサーバ側フック (グローバル変数) ............................................................. 26
Caché Direct の使用法 iii
3.6.1 BeginTaskHook ......................................................................................... 26
3.6.2 IdleHook .................................................................................................. 27
3.6.3 EndTaskHook ............................................................................................ 27
3.6.4 ShutDownHook .......................................................................................... 27
3.7 ユーザ・キャンセル・オプション .............................................................................. 27
4 最善の使用方法 ......................................................................................................... 29
4.1 必要のないプロパティを削除する .......................................................................... 29
4.2 アプリケーションをシャットダウンしたときに明示的に切断する ..................................... 29
4.3 再帰的、または非同期的なサーバ呼び出し ............................................................ 30
4.3.1 クライアント上のタイマ ................................................................................. 30
4.3.2 Visual Basic の DoEvents 関数 .................................................................... 30
5 VisM.ocx コントロールの詳細 ........................................................................................ 31
5.1 VisM 拡張接続文字列の構文 .............................................................................. 31
5.1.1 実行時の接続文字列の形式 ....................................................................... 31
5.1.2 その他の接続文字列の形式 ........................................................................ 32
5.2 VisM プロパティ ................................................................................................. 32
5.2.1 ミラーリングされた VisM プロパティ ............................................................... 32
5.2.2 その他の VisM プロパティ ........................................................................... 33
5.3 VisM メソッド ...................................................................................................... 37
5.3.1 接続メソッドの比較 ..................................................................................... 38
5.4 VisM イベント ..................................................................................................... 39
6 非 ActiveX アプリケーションでの Caché Direct の使用法 .................................................. 41
6.1 一般的な手順 .................................................................................................... 41
6.2 推奨事項 .......................................................................................................... 41
6.3 メモ .................................................................................................................. 42
7 ログ .......................................................................................................................... 43
7.1 クライアントでのログ ............................................................................................ 43
7.1.1 VisM LogMask プロパティ ........................................................................... 43
7.1.2 レジストリ・スイッチ ...................................................................................... 43
7.1.3 レジストリ値の取得と設定 ............................................................................ 44
7.1.4 ログ・ファイルのサイズの制限 ....................................................................... 44
7.2 サーバでのログ .................................................................................................. 45
7.3 サーバ・エラー・グローバル .................................................................................. 45
付録A: インストールとアップグレード ................................................................................. 47
A.1 Caché Direct サーバのアップグレード ................................................................... 47
A.2 新規マシンへの VisM のインストール .................................................................... 47
付録B: 以前のバージョンをお使いの方へのご注意 ............................................................. 49
B.1 Caché Direct での IPv6 に関する問題 ................................................................... 49
B.2 以前の共有接続の動作 ...................................................................................... 50
B.3 新しいアーキテクチャ ......................................................................................... 50
B.4 動作に関する注意 ............................................................................................. 51
B.5 その他のアーキテクチャの変更 ............................................................................ 51
付録C: 例： Visual Basic でのプリンタのサポート ................................................................ 53
C.1 概要 ................................................................................................................ 53
C.2 内部コマンドの構文 ........................................................................................... 53
C.2.1 プロパティの設定 ...................................................................................... 54
C.2.2 プロパティの取得 ...................................................................................... 54
C.2.3 メソッドの実行 ........................................................................................... 54
iv Caché Direct の使用法
このドキュメントについて
このドキュメントでは、プログラマを対象に、ActiveX コントロールや C++ API を使用して Caché サーバと通信するクライ
アントを作成するために Caché Direct を使用する方法について説明します。
このドキュメントの内容は以下のとおりです。
•
"Caché Direct 入門" では、Caché Direct、その主な概念、およびユーザに提供されるツールについて説明します。
•
"VisM コントロールの使用に関する基本" では、VisM コントロールの一般的な使用方法について説明します。
•
"その他の機能" では、カスタム・プロセスを指定して、多様な場合に全体的なクライアントとサーバの相互作用を実
行する方法について説明します。
•
"最善の使用方法" では、Caché Direct での最善のプログラミング方法について説明します。
•
"VisM.ocx コントロールの詳細" では、Caché Direct ActiveX コントロール (VisM.ocx) に関する参考情報について
説明します。
•
"非 ActiveX アプリケーションでの Caché Direct の使用法" では、ActiveX を使用していない (VisM.ocx のない)
C++ などのアプリケーションから Caché Direct のプロパティやメソッドを使用する方法について説明します。
•
"ログ" では、クライアントやサーバのログを可能にする方法について説明します。これは特に問題の診断に役立ち
ます。
また、このドキュメントには以下の付録も付いています。
•
"インストールとアップグレード" では、Caché を再インストールせずにサーバをアップグレードする方法、および
Caché がインストールされていないマシンにクライアント側ソフトウェアをインストールする方法について説明します。
•
"以前のバージョンをお使いの方へのご注意" では、以前のバージョンをお使いの方に特にお知らせしておきたい
アーキテクチャの変更について説明します。この情報は、新しい機能を活用できるようにアプリケーションを適応させ
る場合に役立ちます。
•
"例：Visual Basic でのプリンタのサポート" では、Caché ObjectScript から Windows の既定のプリンタ (VB Printer
オブジェクト) を使用したコールバックの例を示すサンプルについて説明します。
また、完全な目次もあります。
Caché Direct の使用法 1
1
Caché Direct 入門
Caché Direct はクライアント/サーバ接続メカニズムで、TCP 接続を経由して、Windows COM/OLE または C++ クライ
アント・プログラムからサーバ操作を通じて直接制御を提供します。この接続は、非常に高速な、オーバヘッドの低いメカ
ニズムを経由して実行されます。Caché Direct には、Caché セキュリティ、Citrix/Windows Terminal サービスなどに対す
る透過的なサポートが組み込まれています。
名前からもわかるように、Caché Direct は、クライアントから Caché サーバに対して、できる限り最も直接的なアクセスを
提供します。つまり、Caché ObjectScript コマンドはクライアントからサーバに送信され、そこで実行されて、結果がクライ
アントに返されます。Caché Direct は、アプリケーションの 2 つの部分の間に 1 つまたは複数の TCP チャネルをセット
アップし、これらの間でメッセージを管理します。Caché オブジェクトと埋め込み SQL のすべての機能は、Caché Direct
を通じて使用することもできます。クライアントはサーバのすべての機能にアクセス可能で、これを制約できるのは Caché
セキュリティ設定のみです。
複数のサーバ・ジョブ/チャネルを作成し、1 つのクライアント・プロセスから同時に管理し、クライアント・マルチスレッドと
1 つのクライアントから複数のサーバへの接続を同時に実現することができます。
Caché Direct には、サーバからクライアントへのコールバック、クライアントとサーバの両方での制御フローおよび通信ト
ラフィックのログ、メッセージ変換 (圧縮など) のための各種フック、エラー処理、シャットダウン・タスクなどの機能も用意
されています。
注釈
Caché Direct の目的は、Web ベースのアプリケーションの構築に使用することではなく、Direct クライアント/
サーバ・アプリケーションでの使用を想定しています。
1.1 概念
Caché Direct には、Visual Basic プロジェクトや、C++ クライアント対応の C++ インタフェースで最も頻繁に使用される
ActiveX control (VisM.OCX) が用意されています。VisM コントロールには、Caché への接続や送信するコマンドを指定
するためのプロパティやメソッドがあります。
内部的には、VisM コントロールは Caché とは直接通信しません。その代わりに、起動されたコントロールは CDConnect
と呼ばれるオブジェクトにアタッチされます。その後、Caché に接続し、サーバでスレーブ・サーバ・プロセスを起動し、通
信チャネルの管理を行います。CDConnect は複数の VisM インスタンスにアタッチ可能で、すべての VisM インスタン
スから分離されたとしても存在することができ、別のサーバ・プロセスにリダイレクトできます。この柔軟性は、Caché Direct
が次のようにさまざまなアーキテクチャをサポートできることを意味しています。
•
各クライアント VisM が専用のサーバを持っている設定。
•
すべてのクライアント VisM が 1 つのサーバを共有している設定。
Caché Direct の使用法 3
Caché Direct 入門
•
クライアント VisM の集まりが、サーバの集まりを共有し、これらの間を移動して、現在空きのあるものを使用できる設
定。
•
選択されたサーバがアクセスできる特定のデータベースに基づいて、選択されたクライアント VisM がこれらのサー
バを共有する設定。
Caché Direct クライアントは、Caché クライアントをサポートしているすべての Windows プラットフォームでサポートされて
います。
Caché Direct サーバは、Caché サーバ、および DSM をサポートしているすべてのプラットフォームでサポートされてい
ます。
これらのサーバの存在するマシンやデータベースは同じものでも、異なるものでもかまいません。都合に合わせて自由
に配置できます。
1.1.1 用語
Caché Direct コミュニケーション・モデルで使用される用語は以下のとおりです。
•
呼び出し元は Caché を呼び出すクライアント・コードです。これらは通常 VisM インスタンスで、このドキュメントでは
VisM と呼ばれています。これらは C++ コードでもあることもあります。
•
CDConnect は VisM クライアントとサーバの間の中間オブジェクトです。CDConnect は必要に応じて作成され、ク
ライアント・マシンで実行されます。
•
VisM と CDConnect の間の連結は、接続と呼ばれます。
•
CDConnect と Caché サーバ・プロセスの間の TCP 連結はチャネルと呼ばれます。
次の図は、Caché Direct アプリケーションのさまざまな状態を表しています。上の領域 (二重線の上) にある項目はすべ
て、クライアント側の単一プロセス内で実行されています。二重線の下にある項目は、1 つまたは複数の Caché サーバ・
マシンで実行されます。
4 Caché Direct の使用法
使用可能なツールと方法
1.1.2 コミュニケーション・モデル
Caché Direct コミュニケーション・モデルは以下の規則に従います。
•
1 つの VisM が所有できる接続の数は、どのような場合でも、一度に 1 つのみです。つまり、VisM は 1 つの
CDConnect にアタッチされているか、切断されているかのどちらかです。
•
1 つの CDConnect が所有できるチャネルの数は、どのような場合でも、一度に 1 つのみです。つまり、CDConnect
は 1 つの Caché サーバ・プロセスにアタッチされているか、切断されているかのどちらかです。
•
1 つの CDConnect が所有できる接続の数に制限はありません。つまり、どのような CDConnect でも、0、1、または
それ以上の VisM にアタッチできます。これは、複数の VisM が同じサーバ・コンテキストを共有できることを表しま
す。これらの VisM は、各メッセージにより再初期化される変数を除き、同じサーバ・ローカル変数にアクセスします。
次の章の "ミラーリングされた VisM プロパティ" を参照してください。
•
CDConnect を Cache サーバ・プロセスにアタッチする必要はありません。これは、CDConnect が VisM やサーバ・
プロセスから独立しているからです。CDConnect は破棄されるまで存続します。アクセスできなくなった場合 (接続
およびタグがない場合)、または DeleteConnection() メソッドを使って明示的に破棄した場合、CDConnect は自動
的に破棄されます。
注釈
ISCDLink バージョン 220 以前では、CDConnect にアクセスできなくなっても、これが自動的に破棄される
ことはありませんでした。
•
CDConnect は異なる Caché サーバにリダイレクトできます。これはもちろん、この CDConnect にアタッチされてい
る VisM はすべて、新しく選択されたサーバにも効果的にアタッチできるという意味です。
•
Caché サーバ・ジョブはそれぞれ 1 つのスレッドです。したがって、各チャネルでの通信は同期がとられている必要
があります。つまり、1 つのクライアント・メッセージを処理し、これに応答するまで、次のメッセージを読み取ることは
できません。これは、複数の VisM が 1 つの CDConnect を共有している場合、これらの VisM は同時に通信を試
行できないように制約されていることを意味します。通信しようとした場合、“nonsynchronous communication” エラー
が発生します。
•
Caché サーバ・ジョブには、必ず、チャネルが 1 つ必要です。CDConnect からのチャネルを閉じると、対応する
Caché サーバ・ジョブも終了します。
わかりやすいように、たとえ話を使って説明します。CDConnect は 1 本の電話回線につながっているスピーカーフォン
のような動作をします。部屋にいて、電話を聞いている人が VisM で、全員、同じ会話を聞きます。電話の相手は 1 人
で、これが Caché サーバです。この電話を他のサーバに転送すると、すべての VisM がこの新しい相手に接続されま
す。
1.2 使用可能なツールと方法
クライアント側では、Caché Direct は階層化された C++ クラスの集まりで、VisM コントロールにラップされ、必要なプロパ
ティやメソッドをすべて公開します。Caché クライアント・ソフトウェアをインストールすると、このコントロールがインストール
され、登録されるので、Visual Basic などの ActiveX ホストで使用できるようになります。この結果、Caché Direct をいろ
いろなレベルで使用できます。
•
Caché Direct ActiveX コントロールを Visual Basic プロジェクトに組み込むことができます。これにより、アプリケー
ションは (場合によってはユーザとの対話を通じて) プロパティの値を設定し、Caché サーバにコードを送信するメ
ソッドを実行して、結果を表示することが可能です。このドキュメントでは、このテクニックが最も多く使用されることを
前提にしています。
•
C++ プロジェクトで Caché Direct C++ クラスを使用できます。その後、Caché サーバと対話するには、必要に応じ
て、これらのクラスのインスタンスを作成し、プロパティを設定し、メソッドを実行します。
Caché Direct の使用法 5
Caché Direct 入門
サーバ側では、Caché Direct は Caché サーバ環境の透過的な部分です。最新バージョンの Caché 自体をインストー
ルせずに、Caché Direct サーバをアップグレードする必要がある場合には、使用している Caché 環境に最新の Caché
Direct のサーバ・コードを簡単にロードする方法があります。詳細は、このマニュアル末尾の "Caché Direct サーバの
アップグレード" を参照してください。
6 Caché Direct の使用法
2
VisM コントロールの使用に関する基本
この章では、VisM コントロールの使用に関する基本事項について説明します。
•
コントロールへのアクセスと、プロジェクトへのコントロールの追加。
•
Caché への接続と切断。
•
サーバ側コードが実行される Caché ネームスペースの設定。
•
VisM クライアントからのサーバ上のコードの実行
•
クライアントとサーバの間で VisM プロパティをミラーリング。これにより、コードはサーバとクライアントの間で容易に
データを受け渡しできます。
•
コールバック経由で、サーバから、他のクライアント・ユーザ・インタフェース・プロパティやメソッドを参照。
•
Windows の関数や Caché Direct ユーティリティの呼び出し。
この章では、両側のコードに影響を与える可能性のある Caché Direct メッセージの制限についても説明します。最後
に、いくつかの簡単な使用例を掲載します。
注釈
先頭の下線は、Visual Basic ユーザ・リファレンスへのコールバック参照を表しています。このような使用は、
Caché ではどのような場合でもできませんので、注意してください。
2.1 VisM コントロールへのアクセス
Caché クライアント・ソフトウェアをインストールすると、VisM コントロールがインストールされ、登録されるので、Visual Basic
など、どのような ActiveX ホストでも使用できるようになります。
注釈
Caché クライアントがインストールされていないマシンでは、Caché Direct クライアント・ファイルを手作業でコ
ピーし、登録します。詳細は、このマニュアル後半にある、"新規マシンへの VisM のインストール" のセクション
を参照してください。
Visual Basic の場合、このコントロールをプロジェクトに追加するには、[プロジェクト]→[コンポーネント] をクリックし、VisM
にスクロールして、チェック・ボックスにチェックを付けます。次に、他のコントロールの場合と同様に、フォームにこのコン
トロールのインスタンスを追加します。
Caché Direct の使用法 7
VisM コントロールの使用に関する基本
2.2 接続と切断
サーバへの Caché Direct クライアントの接続またはサーバからの切断を実行するには、Server プロパティ、ConnTag
プロパティ、SetServer() メソッド、Connect() メソッド、および DeleteConnection() メソッドを使用できます。これらのツール
にはそれぞれ特有の用途がありますが、重複している部分もあります。SetServer() メソッドと Connect() メソッドは似てい
ますが、これまでの経緯と下位互換性保持のため、多少の違いがあります。SetServer() の 2 つ目の引数を除き、Server
プロパティと SetServer() メソッドは同じです。
付録 "以前のバージョンをお使いの方へのご注意" も参照してください。
2.2.1 接続文字列と接続タグ
Caché に接続するための構文を記述する前に、その構文で使用される接続文字列と接続タグについて知っておくと役
立ちます。
2.2.1.1 基本的な接続文字列
接続文字列は、次の形式を持つ文字列です。
"CN_IPTCP:server[port]"
この引数の最初にある CN_IPTCP は接続メソッドで、必ず TCP です。2 つ目は Caché スーパーサーバが稼動してい
るサーバの名前、または IP アドレスとポートです。例えば、VisM1 という VisM の接続を設定するには、次の構文を使用
します。
VisM1.Server="CN_IPTCP:127.0.0.1[57772]"
この基本文字列を拡張することもできます (詳細は、"VisM.ocx コントロールの詳細" の章にある "VisM 拡張接続文字
列の構文" で説明しています)。この拡張機能は、一般には使用されません。
2.2.1.2 間接参照を使用した接続
代わりに、ローカルに定義されたデータベースのエイリアスに対する間接参照を使用することもできます。この場
合、"@servername" という形式の文字列を使用します。ここでは、servername は Caché Server Manager 内で指定さ
れたものです (Caché サーバ・マネージャの使用法の詳細は、"Caché システム管理ガイド" の "リモート・サーバ接続の
定義" を参照してください)。これらのエイリアスは、クライアント・マシンに対してローカルなものです。クライアント・マシン
が、対応する Caché サーバのエイリアスに対する名前付け規約に従っている場合のみ、この方法でハード・コーディン
グすることができます。
例えば、サーバ名 unix1 への VisM オブジェクト VisM1 の接続を設定するには、次の構文を使用します。
VisM1.Server="@unix1"
注釈
Kerberos 認証を使用する接続を開くときには、間接参照を使用することをお勧めします。Caché サーバ・マネー
ジャでは、認証方法としての Kerberos の設定、接続のセキュリティ・レベルの指定、およびサービス・プリンシ
パル名の定義を行えます。
2.2.1.3 ユーザ・プロンプト
接続文字列を使用できる任意の場所で、この文字列の代わりに二重引用符で囲まれた疑問符 ("?") を使用することが
できます。この場合、クライアント・マシンで定義されているサーバ・エイリアスを 1 つ選択するように求めるプロンプトが
表示されます。
例えば、次の構文を使用すると、ユーザに対して VisM1 という VisM の接続を求めるプロンプトが表示されます。
8 Caché Direct の使用法
接続と切断
VisM1.Server="?"
2.2.1.4 接続タグ
場合によっては、Caché への新しい接続を作成するときに、オプションの接続タグを提供できることがあります。これは、
作成中の CDConnect とそのチャネルに対する名前となります。特定のクライアント・プロセス内で、すべてのタグが一意
であることを確認するのはユーザの責任です。
その後、VisM に接続したときに、接続文字列ではなく、既存の CDConnect の接続タグを指定することができます。明
示的にチャネルを共有するには、この方法が主に使用されます。例えば、VisM1 という VisM の接続を設定するには、
次の構文を使用します。
VisM1.Server="TagA"
また、VisM2 が接続され、タグが割り当てられている CDConnect に VisM1 を接続するとします。接続タグ自体を使用
したくない場合は、次のように ConnTag プロパティを使用できます。
VisM1.Server=VisM2.ConnTag
2.2.2 Caché への接続
接続は VisM を CDConnect にアタッチする動作です (必要に応じて、CDConnect を作成します)。現在、VisM が
CDConnect オブジェクトにアタッチされている場合、まず、これが CDConnect から切断されます。
2.2.2.1 まだ接続されていない場合
VisM がまだ Caché に接続されていない場合、次のいずれかの方法で、Caché に接続します。なお、以下の方法は、一
般的によく使用される順に一覧しています。
•
Server プロパティに、接続文字列 (またはそれに相当するもの) と同じ値を設定します。次に例を示します。
VisM1.Server="CN_IPTCP:127.0.0.1[57772]"
•
最初の引数として、接続文字列 (またはそれに相当するもの) を使用して、SetServer() メソッドを呼び出します。これ
は前の方法と同じです。次に例を示します。
VisM1.SetServer("CN_IPTCP:127.0.0.1[57772]")
•
最初の引数として、接続文字列 (またはそれに相当するもの) を使用して、Connect() メソッドを呼び出します。次に
例を示します。
VisM1.Connect("CN_IPTCP:127.0.0.1[57772]")
どの場合も、Caché Direct により CDConnect が作成され、VisM から CDConnect オブジェクトへの接続が作成されま
す。また、サーバ・プロセスが開始され、CDConnect からサーバ・プロセスへのチャネルが作成されます。
SetServer() または Connect() を使う方法を使用する場合、2 つ目の引数として、接続タグを指定することができます。次
に例を示します。
VisM1.SetServer("CN_IPTCP:127.0.0.1[57772]","tagA")
2.2.2.2 既に接続されている場合
VisM が既に Caché に接続されている場合、CDConnect は既に作成されています。また、関連するサーバ・プロセスも
既に存在する可能性があります。この VisM を元の CDConnect から切断し、新しい CDConnect のためのサーバを作
成して、別の CDConnect に接続することができます。別の CDConnect に接続するには、次の方法のいずれかを使用
します。
Caché Direct の使用法 9
VisM コントロールの使用に関する基本
•
新しい CDConnect を作成し、これに接続するには、接続文字列を 1 つ目の引数として使用して、Connect() メソッ
ドを呼び出します。
•
最後に開かれた CDConnect に接続するには、空の文字列を 1 つ目の引数として使用して、Connect() メソッドを呼
び出します。
•
既存の CDConnect に接続するには、次のいずれかを実行します。
–
Server プロパティに接続タグと等しい値を設定します (Caché 2007.1 以降で可能)。
–
1 つ目の引数として接続タグを使用し、SetServer() メソッドを呼び出します (Caché 2007.1 以降で可能)。
–
最初の引数として、接続タグを使用して、Connect() メソッドを呼び出します。
次に例を示します。
VisM1.Server="tagA"
このような操作の結果、元の CDConnect が破棄されることはありません。また、サーバ・チャネルが存在する場合、これ
が影響を受けることもありません。"CDConnect の破棄" で説明されているとおり、CDConnect は、アクセスが不可能に
なるまで (自動的に破棄されたとき)、または明示的に破棄されるまで存在します。
2.2.3 CDConnect のチャネルの変更
既存の CDConnect のチャネルを変更するには、次の方法のいずれかを使用します。
•
Server プロパティに、接続文字列と同じ値を設定します。
•
最初の引数として、接続文字列を使用して、SetServer() メソッドを呼び出します。
どちらの場合も、CDConnect により、現在接続中のサーバ・プロセスが停止、切断され、その後、新しいサーバ・プロセ
スが開始、接続されます。
2.2.4 Caché からの切断
Caché サーバから切断するには、次の方法のいずれかを使用します。
•
Server プロパティに、空の文字列と同じ値を設定します。
•
最初の引数として、空の文字列を使用して、SetServer() メソッドを呼び出します。
このような操作の結果、CDConnect が破棄されることはありません。また、サーバ・チャネルが存在する場合、これが影
響を受けることもありません。次のセクションで説明するとおり、CDConnect は、アクセスが不可能になるまで (自動的に
破棄されたとき)、または明示的に破棄されるまで存在します。
2.2.5 CDConnect の破棄
CDConnect とそのチャネルを破棄するには、DeleteConnection() メソッドを呼び出します。もちろん、このメソッドにより
サーバ・プロセスも停止します。次に例を示します。
VisM1.DeleteConnection()
2.2.6 方法の概要
以下のテーブルは、Caché との接続および切断方法をまとめたものです。どんな場合でも、Server プロパティを設定す
ることには、SetServer() メソッドの呼び出しと同じ効果があります。
10 Caché Direct の使用法
接続と切断
操作
方法
まだ接続されていない場合に新しい
CDConnect に接続する
以下の方法のいずれかを使用します。
•
Server プロパティに、接続文字列と同じ値を設定します。
•
最初の引数として、接続文字列を使用して、SetServer() メソッドを呼
び出します。
•
最初の引数として、接続文字列を使用して、Connect() メソッドを呼
び出します。
既に接続されている場合に新しい
CDConnect に接続する*
最初の引数として、接続文字列を使用して、Connect() メソッドを呼び出
します。
既存の CDConnect に接続する (既存
の CDConnect がある場合、そこから切
断した後)*
以下の方法のいずれかを使用します。
•
最初の引数として、接続タグを使用して、Connect() メソッドを呼び出
します。
•
Server プロパティに接続タグと等しい値を設定します (Caché 2007.1
以降で可能)。
•
最初の引数として接続タグを使用し、SetServer() メソッドを呼び出し
ます (Caché 2007.1 以降で可能)。
最後に開いた CDConnect に接続する
(既存の CDConnect がある場合、そこ
から切断した後)*
最初の引数として、空の文字列を使用して、Connect() メソッドを呼び出
します。
既存の CDConnect のチャネルを変更
する
以下の方法のどちらかを使用します。
切断する*
CDConnect とそのチャネルを破棄する
•
Server プロパティに、接続文字列と同じ値を設定します。
•
最初の引数として、接続文字列を使用して、SetServer() メソッドを呼
び出します。
以下の方法のどちらかを使用します。
•
Server プロパティに、空の文字列と同じ値を設定します。
•
最初の引数として、空の文字列を使用して、SetServer() メソッドを呼
び出します。
DeleteConnection() メソッドを呼び出します。
重要： * このような操作の結果、CDConnect が破棄されることはありません。また、サーバ・チャネルが存在する場合、
これが影響を受けることもありません。CDConnect は、アクセスが不可能になるまで (自動的に破棄されたとき)、または
明示的に破棄されるまで存在します。
次の図は、Connect() メソッドと SetServer() メソッドの違いをまとめたものです。
Caché Direct の使用法 11
VisM コントロールの使用に関する基本
2.3 ネームスペースの設定
サーバに接続するとき、ネームスペースは最初はスーパーサーバの現在のネームスペースに設定されています。通常、
ここはアプリケーション・コードを実行するに適した場所ではありません。ネームスペースを切り替える方法には次の 3 と
おりがあります。
•
コードで明示的にネームスペースを変更する。これには $ZNAME コマンドを使用します。
•
VisM NameSpace プロパティを使用する。このプロパティは、すべての実行メッセージに入れられ、サーバに送信さ
れます。サーバは、コードを実行する前に、まず、次のロジックを使用して、このプロパティを調べます。NameSpace
が空であるか、サーバの現在のネームスペースと等しい場合、サーバはこのネームスペースに残ります。NameSpace
が現在のネームスペースと異なる場合、サーバのネームスペースを変更してから、コードが実行されます。サーバ・
ジョブは新しいネームスペースに残されます。
•
特別な種類の間接演算を使用することができます。この場合、仮ネームスペースを指定します。これはレジストリ・エ
ントリによって、実行時に実際のネームスペースに変換されます。
正式なネームスペースを確立するには、以下の形式の構文を使用します。
VisM.NameSpace="@MyNS"
ここで、VisM は VisM インスタンスの名前で、MyNS は正式なネームスペースです。
このレジストリは、Cache/CacheDirect/FormalNamespaces にエントリを含む必要があります各エントリはサブキー
です。その名前は仮ネームスペース (例： MyNS) で、translation という名前の文字列値を 1 つ持ちます。この
値はこのマシンで使用される実際のネームスペースです。
このオプションを使用して、テスト・ネームスペースでアプリケーションを簡単にビルドおよびテストし、準備ができた
ら、別のネームスペースに展開することができます。コードを変更する必要はありません。このオプションでは、別々
のマシンで、それぞれ異なるネームスペースを使用して、同一のアプリケーションを使用することもできます。
ネームスペースの変更は比較的コストのかかる操作であることを覚えておいてください。特に、グローバル・バッファとルー
チン・バッファが削除されます。例えば、2 つのネームスペース間のメッセージを交互に使うことは好ましくありません。こ
れは、メモリにデータをバッファする利点がまったくなくなってしまうためです。2 つのネームスペースで交互に作業する
12 Caché Direct の使用法
コードの実行
必要がある場合は、それぞれ専用のネームスペースで稼動する 2 つのサーバ・ジョブに接続を設定します。これにより、
個々のジョブがバッファの効率性を利用できるようになります。
2.4 コードの実行
通常、Caché Direct を使用して、Caché ObjectScript を実行する方法には次の 2 とおりがあります。
•
1 つ目は、Execute() メソッドを使用する方法です。このメソッドの引数は 1 行のコードです。これはコントロールを使
用するための最も一般的で簡単な方法で、コマンド上で ObjectScript コードの行が実行されます。詳細は、この章
の後半にある例を参照してください。
•
2 つ目は、あまり一般的ではない方法ですが、Code プロパティにコードを、ExecFlag プロパティに 1 (すぐに実行
するという意味) を設定することもできます。ExecFlag プロパティを 1 に設定すると同時に、仮想実行ボタンが効果
的に押されます。VisM は即座にメッセージをアセンブルしてサーバに送り、応答を受け取ります。応答が到着する
と、ExecFlag の設定は 0 (アイドル) に戻され、仮想実行ボタンが解放されます。
ExecFlag にその他の設定をして、特別な状況で使用することもできます。詳細は、VisM.ocx プロパティの参照セク
ションを参照してください。
これらの方法の最終的な効果はまったく同じです (Execute() を呼び出すと、クライアントは文字列を一時的に Code プ
ロパティに格納し、内部的に ExecFlag の設定を 1 に変更します)。どちらのメソッドを選択するかは、用途によって異な
ります。コード文字列が変化しない、または別の計算によって選択される場合、ExecFlag を使用する方法のほうが便利
です。1 行のコードを実行する必要があるだけであれば、Execute() を使用する方法のほうが便利で、直接的です。
実行されるコードの行は、正当なコード行または式であればどれでも使用できます。
式の評価には一般的ですが、この場合も、サーバはコード行の先頭を見て、この行が式の形を取っているかどうかを判
断するという便利な規則があります。具体的には、行の先頭に等号が 1 つと、少なくとも 1 つのドル記号が付いている
かどうかがチェックされます。付いている場合、サーバ・コードは "Set VALUE " または "Set VALUE = " のどちらか
を先頭に追加して、VALUE プロパティに式の結果を設定するコマンドを作成します。例えば、クライアント側の "$zv"
は、サーバ側では "Set VALUE=$zv" に拡張されます。この特別な処理を除き、VALUE プロパティはその他のミラー
リングされたプロパティと変わりありません。詳細は、次のセクションを参照してください。
2.5 ミラーリングされたプロパティの使用
Caché Direct では、次のように、クライアントとサーバの間で特定の VisM プロパティの値がミラーリングされます。
1. クライアントはサーバと通信するときに、その他の必要な情報と共に、ミラーリングされたプロパティの値を含むメッ
セージを作成します。サーバはメッセージを受信すると、同じ名前を持つローカル変数を作成し、設定します。
2. サーバ側では、このローカル変数を、その他のローカル変数を使用する場合と同じ方法で使用できます。例えば、
間接指定など、この変数の使用方法に制限はありません。
3. サーバは応答すると、ミラーリングされたプロパティが変更されているかどうかに関係なく、これらすべての値と、その
他の情報を含むメッセージを作成し、送信します。
4. 次に、サーバは ($KILL を使用して) これらのローカル変数を破棄します (ただし、その他のローカル・サーバ変数
はそのまま残されます)。
したがって、呼び出しと呼び出しの間で、ミラーリングされた変数がサーバに残されることはありません。これらの変
数はサーバがクライアント・コマンドを実行している間のみ存在します。
Caché Direct の使用法 13
VisM コントロールの使用に関する基本
2.5.1 ミラーリングされた基本的な値の使用
ミラーリングされた基本的な VisM プロパティは、文字列プロパティ P0、P1、P2、P3、P4、P5、P6、P7、P8、P9、および
VALUE です。サーバがクライアント・コマンドを実行しているときに、サーバ・プロセスは、VisM のプロパティと同じ値を
持つ、同じ名前のローカル値を持っています。サーバでの変更に続いて、クライアントがサーバから応答メッセージを受
信したときに、クライアントでプロパティが変更されます。
VALUE プロパティにはもう 1 つ機能が用意されています。"コードの実行" に説明されているとおり、Code プロパティの
値が式である (つまり、先頭にドル記号または等号が付いている) 場合、サーバは、VALUE プロパティに指定されてい
る式の結果を返します。
2.5.2 PLIST の使用
もう 1 つミラーリングされる VisM プロパティがあります。それは PLIST プロパティです。Caché Direct はこのプロパティ
を使用して、配列上の値をサーバとクライアントの間で受け渡します。クライアントと Caché では配列の表現方法が異な
るため、サーバからクライアント、およびクライアントからサーバへの両方向での変換を理解することが重要です。PLIST
プロパティの形式は、これら 2 種類の環境に応じて異なります。
•
クライアントでは、PLIST は、すべての “配列” 要素を持つリストで、要素と要素は区切り文字で連結されています。
この区切り文字は、クライアントでのみ使用されている PDELIM プロパティで指定されています。例えば、PDELIM
が "^" である場合、PLIST は、"first^second^third" のようになります。
•
サーバでは、PLIST は 1 次元配列で、次の形式を取ります。
–
PLIST には、クライアントのリストに含まれる項目数を表す数値が入ります。
–
PLIST(1) には、リストの先頭項目が含まれます。
–
PLIST(2) には、リストの 2 番目の項目が含まれます。
–
以降、同様に繰り返されます。
PDELIM プロパティが空の文字列である場合、PLIST は単一の文字列と見なされます。
サーバは、応答メッセージをアセンブルするときに、PLIST を次のように扱います。
•
PLIST が、現在リストに含まれている要素の数と同じである場合、サーバは、そのまま PLIST 配列を返します。
•
PLIST が現在リストに含まれている要素の数を下回る場合は、サーバは、リストの末尾から要素を削除して、PLIST
配列を調整します。
例えば、クライアントに次のコードがあるとします。
VisM1.PDELIM = "^"
VisM1.PLIST = "armadillo^beaver^cobra"
サーバには次のように表示されます。
–
PLIST=3
–
PLIST(1)="armadillo"
–
PLIST(2)="beaver"
–
PLIST(3)="cobra"
その後、サーバで次のコードを実行するとします。
Set PLIST(3)="cat"
Set PLIST(4)="donkey"
14 Caché Direct の使用法
Visual Basic ユーザ・インタフェースへのコールバック
クライアントに戻ったときの、PLIST プロパティは "armadillo^beaver^cat" です。3 つめのリスト要素は更新されていま
すが、4 つめのリスト要素は返されません。これは、リストの個数が更新されていないからです。
•
PLIST が現在リストに含まれている要素の数を上回る場合は、サーバは、空の文字列を要素として PLIST 配列に
追加し、これらを空のリスト位置に追加して調整します。
前の例を使って、今度は、サーバ・コードが次のようになっている場合を考えてみましょう。
Set PLIST=5
Set PLIST(5)="eagle"
この場合、クライアント・プロパティは "armadillo^beaver^cobra^^eagle" になります。
•
PLIST が正の整数ではない場合、サーバは、数値以外の添え字を持つ要素を含め、リスト内の要素の数を数え、こ
の個数を PLIST に設定します (対照的に、ここまでに挙げたすべての例では、サーバは数値の添え字を持つ配列
要素のみを返します)。
ただし、個数と返される値の両方とも $Order を使って計算されます。これには、配列には連続する番号の付いたエ
ントリが必要であるという要件を排除する効果があります。つまり、Caché に用意されている文字列の添え字と自動
ソートを使用できます。
したがって、次のコードはどちらも、上記の 4要素の例と同じ結果となります。
Set PLIST=""
Set PLIST(10)="donkey"
または
Set PLIST=""
Set PLIST("don")="donkey"
前述の動作は、一般に、サーバでリスト要素の数が変わると、PLIST が新しい個数に更新されるか、PLIST がクリアされ
る (その後、サーバにリスト要素の個数を数えさせる) ことを意味しています。
2.6 Visual Basic ユーザ・インタフェースへのコールバック
Visual Basic を使用する場合、VisM には、Caché ObjectScript コードがクライアント・ユーザ・インタフェースの要素を参
照できるようにする特別な機能が用意されています。このようなプロパティやメソッドの参照はコールバックと呼ばれま
す。これは、参照するときに、サーバからクライアントにメッセージが送信されるからです。クライアントはフォームとコント
ロールを検索し、OLE 呼び出しを発行して、結果をサーバに返します。
特に、getter および setter メソッドを使用して、クライアント・ユーザ・インタフェース上のどのコントロールのプロパティに
でもアクセスできます。また、フォームに次の Visual Basic メソッドを提供するコントロールが含まれている場合、ObjectScript
でこれらのメソッドを使用することができます。
•
AddItem()
•
RemoveItem()
•
Refresh()
•
Move()
•
Clear()
•
Hide()
•
Show()
•
SetFocus()
Caché Direct の使用法 15
VisM コントロールの使用に関する基本
2.6.1 Visual Basic コールバックをサポートするための要件
特定のフォームでコールバックを使用できるようにするための要件は次の 2 つです。
•
このフォームには VisM コントロールが含まれていなければなりません。
•
そのフォーム上のコントロールへの最初のサーバ参照をする前に、(通常は、Form_Load イベント・コールで) 次のよ
うな呼び出しを行います。
CreateDispatch Me, VisM1
ここで、Me は現在のフォームへの Visual Basic 参照で、VisM1 はそのフォーム上での VisM 名です。CreateDispatch
関数は <cache-install-dir>\dev\cdirect\VBRUN.BAS モジュールの一部です。プロジェクト内にこのモジュールが
含まれていなければなりません。この関数は、フォーム上にコントロールのリストを作成し、将来の参照に備えて、こ
れらのコントロールを VisM の非表示プロパティに格納します。
2.6.2 コントロールのプロパティの参照
コントロールのプロパティを参照するには、以下の特別な ObjectScript 構文を使用します。
_[formname!]controlname[(controlindex)].propertyname[(propertyindex)]
角かっこ内の要素は省略可能です。また、かっこ類は構文の一部ではありません。先頭の下線は必須です。formname
を省略した場合、このフォームは、VisM から現在のメッセージが送信されているフォームであると見なされます。controlname
と propertyname は省略できません。コントロールがコレクションの 1 つである場合、controlindex を指定する必要があり
ます。プロパティがコレクションである場合は、propertyindex は必須です。例えば、現在のフォームにあるテキスト・コント
ロール txt1 のテキスト・プロパティを取得するには、次のコードを使用します。
Set x=_txt1.Text
テキスト・プロパティを設定するには、次のコードを使用します。
Set _txt1.Text="something"
ObjectScript では、下線も連結演算子なので、その意味が不明確な場合には、かっこを使用してください。
2.6.3 コントロールのメソッドの実行
コントロールのメソッドを実行するには、以下の構文を使用します。
Do _[formname!]controlname[(controlindex)].method[(args)]
例えば、リスト・ボックス list1 に項目を追加するには、次のコードを使用します。
Do _list1.AddItem("item data")
2.7 Windows 関数や Caché ユーティリティ機能の使用
ObjectScript コードは、以下の一般的な Windows 関数を使用することもできます。
•
MsgBox(message,style, title)
•
DoEvents
•
WinExec(name,flag)
16 Caché Direct の使用法
メッセージ制約の理解
また、以下の Caché Direct ユーティリティを使用することが可能です。これらも、%CDSrv ルーチンに含まれます。
•
GetClientIP() はクライアントの IP アドレスを返します
•
GetSvrNode() はサーバ・マシンの名前を返します
•
GetTCPDevice() このチャネルにサービスを提供する TCP デバイスの識別子を、Caché 形式で返します
これらの関数の実行には、次のような構文を使用します。
Set varname=$$function^%CDSrv(arguments)
例えば、Windows MsgBox 関数を呼び出すには、次のようなコードを使用します。
Set reply=$$MsgBox^%CDSrv("Are you finished?",1)
2.8 メッセージ制約の理解
CDConnect とサーバの間の通信はすべて、Caché Direct メッセージにより行われます。これらのメッセージは、すべて
のコンポーネントがローカルである場合でも、TCP 接続経由で送信されます。
メッセージには、メッセージ内で内容が送信されるプロパティを設定する方法について、一定の制約が課せられていま
す。これらの制約は、コールバックの記述方法にも影響を与えます。メッセージの詳しい内部構造を知る必要はありませ
んが、一般的な概要を知っておくと便利です。通常、メッセージは 56 バイトのヘッダから始まり、これに複数のデータ用
フィールドが続きます。ヘッダ内のフラグはメッセージのタイプを記述します。これは、どのようなフィールドが続くかを暗
黙に示しています。メッセージのタイプには、NewTask、BeginTask、ExecuteCode、EndTask などがあります。内部
情報に加えて、メッセージには、ミラーリングされたプロパティと、その他の VisM プロパティのセクションで説明する、そ
の他のプロパティが数個含まれます。
2.8.1 Unicode とロケールの問題
サーバに送信されるすべてのプロパティについて、その値に使用できるのはテキスト文字のみです。この制約は、Caché
Direct により設定または取得される Visual Basic プロパティすべてに適用されます。詳細は、クライアント・ユーザ・イン
タフェースへのコールバックのセクションを参照してください (一部の環境での作業では、この制約に対する例外もあり
ますが、この場合でも一般的な要件は存在します。)
Caché サーバは、8 ビットまたは 16 ビット (Unicode) モードのいずれかで動作します。クライアントとサーバの間の最初
の通信では、サーバはクライアントにサーバのモードを知らせます。次に、以下の操作を行います。
•
サーバが Unicode の場合、すべてのクライアントはすべての文字列を Unicode に変換してから、サーバに送信しま
す。この結果、メッセージのサイズが大きくなる可能性がありますが、どのロケールで動作しているどのクライアントで
も、サーバと確実に通信できるようになります。
•
サーバが 8 ビット・モードの場合、クライアントによる文字列の変換は一切行われません。サーバと同じロケールを使
用していないクライアントがある場合、サーバがデータベースに書き込みを行ったときにデータが失われるか、混乱
する可能性が高くなります。これは、一部の文字では、ロケールが変わると意味も変わるためです。したがって、クラ
イアントから受信したものを変換するか、翻訳するかはアプリケーションの責任になります。
Caché Direct の使用法 17
VisM コントロールの使用に関する基本
注釈
プロパティは文字列でなければならないという要件は、Unicode サーバで実行される変換に起因しています。
ただし、8 ビット・サーバの場合、および $c(1) から $c(31) の範囲の値を持つコントロール・コードの場合は、テ
キスト以外のデータも保持されます。
8 ビット・サーバでは変換は行われないため、データが壊れることはありません。また、低範囲のコントロール・
コードは 8 ビット・ロケールでも、Unicode でも同じなので、どのサーバでも問題にはなりません。
ただし、クライアントは C++ で記述されており、C 文字列規則を使用しているため、埋め込まれている Null 値
($c(0)) により、文字列が切り捨てられる可能性があります。
2.8.2 メッセージのサイズ
これまでの経緯から、クライアントとサーバの間ではどちらの方向でも、1 つのメッセージの最大サイズは 32Kb に制限さ
れています。Caché Direct では、長いメッセージが複数の短いメッセージに分割されることはありません。また、長すぎる
メッセージの送信が試行された場合、復旧できません。したがって、この制限を超えるメッセージが作成されないようにす
る責任はアプリケーションにあります。これよりも長いデータを送信するには、一連のメッセージを送信します。この場合、
テストの結果で速度が犠牲にならないことが判明しています。これは、送信のために、TCP により、大きなメッセージが小
さなセグメントに分割されるためです。その他の条件が同じである場合、12 ～ 20 KB のメッセージで最適速度 (1 秒当
たりの総バイト数) が実現すると考えられます。
メッセージのサイズを見積もるには、サーバに送信される VisM プロパティに含まれるすべての文字に、数百バイトのオー
バーヘッドを加味して考慮します。送信されるプロパティは、ミラーリングされたプロパティと、数個の小さなプロパティ
(CODE や NameSpace など) です。通常のメッセージには、約 10 個のフィールドと PLIST プロパティがいくつかありま
す。これらのプロパティはそれぞれ、フィールドとして送信されます。サーバが 8 ビットの場合、または文字列がすべて
Latin-1 文字の場合、データ・フィールドは 1 文字あたり 1 バイトです (Latin-1 文字を Unicode で表現した場合、上位
バイトにはオンになっているビットはありません。このような文字列は、8 ビット文字列として送信できます)。サーバが
Unicode で、プロパティに Latin-1 以外の文字が含まれている場合、このフィールドには 1 文字あたり 2 バイトが含まれ
ます。この結果、メッセージの最大容量は、約 30,000 文字ではなく、その半分未満になります。効率を犠牲にしないた
めに、どのメッセージも約 12,000 文字を超えないように確認することをお勧めします。
2.9 例
2.9.1 簡単な例： Lightweight Caché ターミナル
これは Visual Basic で 1 つのクライアント・フォームを作成する方法を示した小さなサンプル・アプリケーションです。ユー
ザはこれを使用して、Caché ObjectScript を 1 行入力し、結果を得ることができます。このアプリケーションでは、可能な
限り既定値が使用されています。また、エラー・チェックはほとんど行われません。
このサンプルでは、ローカル・マシンに Caché サーバが実行されていること、Caché Direct コンポーネントがインストール
されていることを前提にしています。使用しているマシンで Caché が実行されていることを確認してください。
Visual Basic を起動します。フォームを使用して、新しい Standard EXE プロジェクトを作成します。[プロジェクト] または
[コンポーネント] メニューを使用して、ツールボックスに VisM コントロールを追加します。このフォームに、コマンド・ボタ
ンを 1 つ (Command1)、テキスト・ボックスを 2 つ (Text1 および Text2)、VisM コントロールを 1 つ追加します。1 つ目
のテキスト・ボックスは、簡単な Caché ObjectScript の 1 行が入る程度の幅にします。また、2 つ目のテキスト・ボックスは
結果文字列が入る程度の大きさにします。Command1_Click イベント・コードに、以下を入力します。
VisM.Execute Text1.Text
If VisM1.Error <> 0 Then
Text2.Text = "Error " & VisM1.Error & ": " & VisM1.ErrorName
Else
Text2.Text = VisM1.VALUE
Endif
18 Caché Direct の使用法
例
Form_Unload メソッドに、次の行を追加します。
VisM1.Server = ""
プロジェクトを実行します。フォームが表示されたら、コマンド・ボタンをクリックします。[Choose Server Connection] ダイ
アログが表示されます。[LOCALTCP] を選択し、[OK] を押します。[Text1] フィールドは空のままにしておいて、
[Command1] コマンド・ボタンをクリックします。[Text2] に構文エラー・メッセージが表示されます。これは、Caché
ObjectScript の行を入力しなかったためです。
[Text1] に「$H」と入力します。コマンド・ボタンをもう一度クリックします。現在日時が、$H 形式で [Text2] に表示さ
れます。
アプリケーションを終了します。
2.9.1.1 説明
コマンド・ボタンをクリックすると、[Text1] の内容が一時的に VisM Code プロパティに格納され、VisM Execute() メソッ
ドを使って実行するためにサーバに送信されます。“Text1” (テキスト・ボックスの既定値) は有効な Caché ObjectScript
ではないので、1 回目のクリックでは、Error および ErrorName プロパティに構文エラーが返されます。Command1_Click
イベント・ルーチンのコードにより、[Text2] にエラーが表示されます。
2 回目のクリックでは、サーバにより、指定されたコードが実行され、VALUE プロパティに現在の $H が設定されます。
Command1_Click イベント・ルーチンのコードにより、再度、VALUE プロパティの内容が [Text2] テキスト・ボックスに表
示されます。
終了すると、Form_Unload イベント・ルーチンのコードにより、Server プロパティに空の文字列が設定され、クライアント
はサーバから正常に切断されます。
これは明らかに非常に単純な例ですが、非常の強力でもあります。ObjectScript の行はどれもクライアントで実行でき、
どの (小さな) 結果も取得して表示できます。グローバルからの値を取得できます。計算を実行し、結果を返すことができ
ます。$JOB を使用して、処理に長時間かかるバックグラウンド・プロセスを開始できます。
2.9.2 その他の例
以下のサンプル・コードを考えてみましょう。
VisM1.P0 = "pig"
VisM1.Execute "Set VALUE=$e(P0,2,$l(P0))_$e(P0,1)_""ay"""
Print VisM1.VALUE
このコードの結果、VALUE プロパティは "igpay" に設定されます。多少詳しく説明すると、P0 プロパティはサーバに送
信され、P0 という名前のローカル・サーバ変数になります。サーバはコード行を実行し、VALUE という変数を計算して、
クライアントにメッセージを返します。これに応じて、クライアントは VALUE プロパティを更新して出力します。
Caché Direct の使用法 19
3
その他の機能
前の章では、Caché Direct を使用するクライアント・アプリケーションの基本要件について説明しました。この章では、カ
スタム・プロセスを指定して、多様な場合に全体的なクライアントとサーバの相互作用を実行する方法について説明しま
す。これらの機能の多くは、典型的なクライアントとサーバの相互作用の特定の部分に含まれるフックで、その大半は
サーバ固有の機能です。クライアントにも追加されている機能があります。
この章には、以下のセクションが含まれます。
•
概要
•
エラー・トラップ
•
キープ・アライブ機能
•
サーバの読み取りループと終了確認
•
フックの読み取りと書き込み
•
サーバ側フック (グローバル変数)
•
クライアントでのユーザ・キャンセル・オプション
3.1 概要
このセクションでは、クライアントとサーバの相互作用の概要と、一般的なサーバ動作について説明します。まず、典型
的なクライアントとサーバの相互作用は、次のステップから構成されています。
1. クライアントはサーバに接続し、サーバ宛に NewTask メッセージを送信します。
2. 次に、クライアントは BeginTask メッセージを送信します。
ライセンス・スロットが使用できない場合、サーバは <No License> エラーを返して切断します。
3. サーバは BeginTaskHook をチェックします。ここには、サーバで独自に実行する処理を追加することができます。
4. 次に、クライアントは通常、必要な数の ExecuteCode メッセージを送信します。クライアントが個々のメッセージを送
信する直前に、クライアント側書き込みフックがあります。ここに、独自の処理を追加することができます。
5. サーバはメッセージを受信すると、サーバの読み取りフック (ReadHook) で指定された処理をすべて実行し、メッセー
ジを読み取ります。
6. サーバは、要求されたとおりコードを実行します。
7. サーバは、サーバ書き込みフック (WriteHook) で指定された処理をすべて実行し、メッセージを送信します。
Caché Direct の使用法 21
その他の機能
8. クライアントはメッセージを受信すると、クライアント側の読み取りフックで指定された処理をすべて実行し、メッセー
ジを読み取ります。
9. やり取りの最後に、クライアントは EndTask メッセージを送信します。これにより、接続が切断されます。
10. サーバは EndTask メッセージを受信して、EndTaskHook をチェックします。ここには、サーバで独自に実行する処
理を追加できます。
11. サーバは ShutDownHook をチェックします。これには、独自の処理を追加できます。その後、サーバはシャットダウ
ンします。
注釈
カスタム EndTask 処理とは対照的に、ここで説明するクライアントとサーバの相互作用以外に、カスタム・
シャットダウン処理も行われます。タイムアウト・エラーなど、何らかの理由でサーバがシャットダウンした場
合、シャットダウン処理が行われます。
この説明からわかるとおり、Caché Direct により、メッセージを送信する直前 (書き込みフック)、およびメッセージの受信
直後 (読み取りフック) に処理を挿入するためのフックが用意されています。これらのフックは、カスタム・ログ、圧縮、暗
号化など、アプリケーションにより選択された目的で使用することができます。クライアントの書き込みフックは、サーバの
読み取りフックと、またクライアントの読み取りフックはサーバの書き込みフックと対になっています。書き込みフックにより
メッセージが変換された場合、対応する読み取りフックで、このメッセージが Caché Direct で予期される形式になってい
ることを確認する必要があります。
3.2 エラー・トラップ
サーバは致命的ではないエラーをすべてトラップし、次の手順を通じて、クライアントにレポートします。
1. サーバのローカル変数、error と errorcode に値を設定します。
2. ローカル・エラー・フック (%cdEHOOK) で指定された関数を呼び出します。
3. クライアントにメッセージを送信し、サーバのローカル変数 error と errorcode に現在の値を渡します。
3.2.1 %cdEHOOK ローカル変数
%cdEHOOK エラー・フックは、サーバの (つまり、個々のジョブ内の) ローカル変数です。このフックを使用するには、ルー
チン名を含む文字列を $$label^rtn の形式で設定します。エラーが発生したときに、サーバはこの変数を評価しま
す。変数が空ではない場合、サーバはこのルーチンを呼び出します。変数が空の場合、サーバは次の手順に進みます。
このフックは、エラー処理を追加で指定する場合に使用します。例えば、エラー・メッセージを拡張することができます。
関数はローカル変数、error および errorcode を自由に使用できます。ただし、残りのエラー処理ルーチンでこれらを使
用不可能にしない (つまり、変数は依然として定義されており、2 バイト以内のテキストまたは数値である) ことが前提で
す。例えば、クライアントのアプリケーション・コードで活用できるように、エラー番号やテキストを変更または拡張できま
す。
3.3 キープ・アライブ機能
クライアント/サーバ・アプリケーションでは、クライアントやサーバが相互に接続できなくなる原因は多数あります。Caché
Direct には、クライアントとサーバに対して、定期的に接続を確認し、接続が失われた場合には適切に対応するための
手段が用意されています。サーバの場合、適切にシャットダウンすることが唯一の意義ある対応です。しかし、クライアン
トでは、例えば、新しいサーバ接続を確立したり、ユーザにメッセージを表示したりすることができます。
22 Caché Direct の使用法
キープ・アライブ機能
この機能には以下の要素が含まれます。
•
キープ・アライブ間隔の初期設定。詳細は、次のセクションで説明します。
•
キープ・アライブ間隔とタイムアウトを表すクライアントのプロパティ。詳細は、次のセクションで説明します。
•
クライアントでの ShutDown イベント。詳細は次のセクションで説明します。
•
独自の処理を追加するためのサーバのフック。ShutDownHook は、サーバがシャットダウンしたときに必ず使用され
ます。詳細は、この章後半の "その他のサーバ側フック (グローバル変数)" のセクションを参照してください。
3.3.1 初期のキープ・アライブ間隔
キープ・アライブ間隔 5 回分のうちに、クライアントからのメッセージを受信できなかった場合、サーバはシャットダウンし
ます。サーバの起動時、KeepAliveInterval の初期値は 17,280 秒 (1 日の 1/5) です。したがって、既定の設定では、
17,280 秒のキープ・アライブ間隔が 5 回 (合計 86,400 秒 (24 時間)) 経過するまでにクライアントから何の連絡もない
と、サーバはシャットダウンします。通常は、300 (5 分間) のような低めの値に設定するのが適当です。
3.3.2 キープ・アライブ設定 (クライアント)
クライアントはキープ・アライブ間隔を制御し、サーバにキープ・アライブ・メッセージを送信するたびに、この値を再送信
します。VisM には、キープ・アライブの動作を制御するためのプロパティが 2 種類あります。
•
KeepAliveInterval プロパティは、キープ・アライブ・メカニズムのために、通信のアイドル時間を秒単位で指定しま
す。ここで指定された秒数、クライアント/サーバ通信が行われなかった場合、クライアントからサーバにキープ・アラ
イブ・メッセージが送信されます。KeepAliveTimeOut プロパティで指定された期間、クライアントに応答が届かなけ
れば、クライアントは ShutDown イベントを起動します。応答が届いた場合は、もう一度待機し、もう 1 つのキープ・
アライブ・メッセージを送信します。
•
KeepAliveTimeOut プロパティは、キープ・アライブ・ラウンド・トリップのタイムアウトを表します。この値は通常のタイ
ムアウト時間、TimeOut よりも短くなければいけません。
3.3.3 キープ・アライブ・エラーのシャットダウン・イベント (クライアント)
前述のように、クライアントは、キープ・アライブ・メッセージに対する応答を受信しなかった場合、次の操作を行います。
1. ConnectionState プロパティの値を変更します。
このプロパティは、常に、接続の状態を表しています。ConnectionState が 0 の場合、接続には問題がないか、切
断が正常に行われています。このプロパティの値が 0 以外の場合、サーバから切断された時刻 (午前 0 時からの
経過秒数) を表しています (これは $Horolog の秒部分と同じです。日付は示されませんが、最新であると見なされ
ます)。
2. その後、ShutDown イベントが起動され、このイベントに 1 つの引数、つまり、ConnectionState プロパティの現在の
値が渡されます。
接続が失われた後に、クライアントがメッセージを送信しようとすると、<ServerLost> エラーが発生します。
注釈
このイベントは、前述のとおり、クライアントがキープ・アライブ・メッセージに対する応答を受け取らなかった場
合にのみ、トリガされます。
Caché Direct の使用法 23
その他の機能
3.4 サーバの読み取りループと終了確認
Caché Direct サーバ・プロセスの設定後、このプロセスは、制限時間付きの読み取りで始まるポーリング・ループ内で、
クライアントからの通信を待ち受けます。読み取りのタイムアウトは 10 秒間です。タイムアウトする前に読み取りが完了す
ると、サーバはクライアントとの通信を処理し、応答メッセージをクライアントに送信して、ポーリング・ループの先頭に戻り
ます。しかし、先にタイムアウトすると、サーバは指定された手順に従って、このサーバ・プロセスをシャットダウンするかど
うかを判断します。詳細は、次のセクションで説明します。
3.4.1 サーバの終了確認手順
読み取りループがタイムアウトした場合、サーバは指定された手順に従って、このサーバ・プロセスをシャットダウンする
かどうかを判断します。シャットダウンする必要があると判断した場合、サーバは ShutDownHook を呼び出し、そこで指
定された処理を実行してからシャットダウンします。それ以外の場合、終了確認手順で指定された次の手順に進みます。
この手順では、次のように、複数のサーバ側フックが使用されています。
1. ローカルのアイドル時間フック (%cdPULSE) に指定された関数を呼び出し、要求された場合は、アイドル時間処理
を実行します。関数から 0 が返された場合は、サーバは、サーバの終了確認手順を継続します。関数から 1 が返
された場合は、サーバはシャットダウンします。
2. グローバルのアイドル時間フック (IdleHook) に指定された関数を呼び出し、要求された場合は、アイドル時間処理
を実行します。関数から 0 が返された場合は、サーバは、サーバの終了確認手順を継続します。関数から 1 が返
された場合は、サーバはシャットダウンします。詳細は、この章後半の "その他のサーバ側フック (グローバル変数)"
のセクションを確認してください。
3. クライアントとの最後の通信から経過した時間を計算します。クライアントからの通信なしに、キープ・アライブ間隔 5
回分を超える時間が経過している場合、サーバはシャットダウンします。
4. システムがシャットダウン信号を受信したかどうかを確認します。受信している場合、サーバはシャットダウンします。
5. サーバが Stop^%CDSrv コマンドを受信したかどうかを確認します。受信している場合、サーバは Caché Direct サー
バ・ジョブをすべてシャットダウンします。
6. サーバが StopJob^%CDSrv コマンドを受信したかどうかを確認します。受信している場合、サーバは指定されたサー
バ・ジョブをシャットダウンします。
7. スレーブ・サーバを終了する必要があるかどうかを確認します。終了する必要がある場合、サーバはシャットダウンし
ます。
注釈
どの手順でも、サーバをシャットダウンする必要があることが確認されると、シャットダウン・フック (ShutDownHook)
が呼び出され、そこで指定された処理がすべて実行され、その後シャットダウンされます。
3.4.2 %cdPULSE ローカル変数
この %cdPULSE フックは、ローカル変数としてのみ (つまり、個々のサーバ・ジョブ内にのみ) 存在します。このフックを使
用するには、関数呼び出しを含む文字列を $$label^rtn の形式で設定します。前のセクションで説明したとおり、サー
バは、指定されたタイミングで、この変数を評価します。変数が空ではない場合、サーバは指定された関数呼び出しを
実行し、その結果が 0 または "" でない場合は終了します。変数が空の場合、サーバは次の手順に進みます。
24 Caché Direct の使用法
フックの読み取りと書き込み
3.5 フックの読み取りと書き込み
前述のとおり、Caché Direct により、メッセージを送信する直前 (書き込みフック)、およびメッセージの受信直後 (読み取
りフック) に処理を挿入するためのフックが用意されています。これらのフックは、カスタム・ログ、圧縮、暗号化など、アプ
リケーションにより選択された目的で使用することができます。クライアントの書き込みフックは、サーバの読み取りフック
と、またクライアントの読み取りフックはサーバの書き込みフックと対になっています。書き込みフックによりメッセージが変
換された場合、対応する読み取りフックで、このメッセージが Caché Direct で予期される形式になっていることを確認す
る必要があります。
注釈
予期されるメッセージ形式
メッセージの先頭 4 バイトは、メッセージの長さを表す 32 ビットの整数です。メッセージの長さを変更した場合
は、必ず、この値を変更してください。
サーバ・ルーチンとクライアント・ルーチンが適切に対応していることを確認するのは、プログラマの責任です。
3.5.1 サーバ側の読み取りフックと書き込みフック
サーバ側のフックは、その他のサーバ側フックと同じ一般的なメカニズムを使用します。詳細は、"その他のサーバ側フッ
ク (グローバル変数)" のセクションを参照してください。
3.5.1.1 ReadHook
ExecuteCode メッセージの受信後、直ちにサーバで実行する必要がある処理を指定するには、このフックを使用します。
サーバはクライアントから ExecuteCode メッセージを受信した直後、ミラーリングされたプロパティに値を割り当てる前に、
このフックを呼び出します。
関数では、ローカル変数 %cdMSG が使用されます。この変数には受信メッセージが入っています。関数は、そのアクショ
ンを実行し、変換後のメッセージを返します。メッセージが変更されなかった場合は、単に終了 (Quit ^%cdMSG) しま
す。
3.5.1.2 WriteHook
クライアントに応答を送信する前に、サーバが実行する必要がある処理を指定するには、このフックを使用します。サー
バは、クライアントにメッセージを送信する直前に、このフックを呼び出します。
関数では、ローカル変数 %cdMSG が使用されます。この変数には送信メッセージが入っています。関数は、そのアクショ
ンを実行し、変換後のメッセージを返します。メッセージが変更されなかった場合は、単に終了 (Quit ^%cdMSG) しま
す。
3.5.2 クライアント側の読み取りフックと書き込みフック
クライアント側でフックをインストールするには、VisM.ocx ファイルと同じディレクトリに、CDHooks.dll という DLL を作成し
ます。フックは、次のように特定の名前と署名を持つエントリ・ポイントです。
unsigned char* ReadHook(unsigned char* pInMsg);
unsigned char* WriteHook(unsigned char* pInMsg);
void FreeHookMem(unsigned char* pMem);
ReadHook および WriteHook ルーチンは、次のように動作すると見なされています。
•
入力引数として、バイトのブロック、つまり受信メッセージへのポインタを取ります。
•
データのブロックへのポインタを返します。
Caché Direct の使用法 25
その他の機能
•
新たに割り当てられたデータへのポインタを返します (この場合、クライアントは新しいデータ・ブロックをコピーし、
FreeHookMem ルーチンを使って、返り値を解放します)。
返り値と引数が同じである場合、メモリは解放されません。これは、データが変更されていないか、元のメッセージと同じ
領域を占めている場合に起こる状況です。サーバ側のルーチンに適切に対応するクライアント・ルーチンを記述するの
はユーザの責任です。
FreeHookMem ルーチンは、別のルーチンにより割り当てられたメモリを解放します。
3.6 その他のサーバ側フック (グローバル変数)
このセクションでは、グローバル変数に保存されているその他のサーバ側フックに関する参考情報について説明します。
•
BeginTaskHook
•
IdleHook
•
EndTaskHook
•
ShutDownHook
このセクションで説明するフックはすべて、同じ一般的なメカニズムを使用します。グローバル ^%CDSwitch("HookName")
に対して値を指定します。この値は、$$label^rtn の形式で記述された関数呼び出しを含む文字列です。このグロー
バルは、指定されたタイミングで、サーバにより評価されます。詳細は、この章の概要のセクションを参照してください。グ
ローバルが空ではない場合、サーバは、指定された関数呼び出しを実行します。グローバルが空の場合、サーバは次
の手順に進みます。
これらすべてについて、実行は次のように、間接指定により行われます。
Set @("r="_^%CDSwitch("HookName"))
ここで、r は返り値です。
3.6.1 BeginTaskHook
このフックは、保護パラメータの調整や、プロセスのネームスペースの変更などの作業に使用します。サーバは、サーバ・
ジョブの作成後、コードの実行前に、このフックを呼び出します。詳細は、この章の概要のセクションを参照してくださ
い。
関数は、次のローカル・サーバ変数を引数として使用できます。
•
username – Caché Direct ユーザ名
•
taskname – myapp.exe など、クライアントで実行されている実行可能ファイルの名前
•
clientIP – クライアントの IP アドレスで、127.0.0.1 のように文字列の形式で表されています。これは、クライアント
の接続方法に応じて、便利な場合とそうでない場合があります。例えば、非 TCP Citrix 接続は、形式的な IP アド
レスを受け取ることにより、Caché ライセンス・システムの要求を満たします。
関数は次のいずれかの値を返します。
•
成功 (値 0)
•
エラー (^errornumber^errorname" という形式の文字列。ここで、errornumber は 0 ではありません)。Caché Direct
エラー番号の 20900 ～ 20999 は、アプリケーション・エラーのために予約されています。エラーが発生した場合、エ
ラー番号とテキストが VisM プロパティ、Error および ErrorName に表示され、エラー・イベントの信号が送られま
す。
26 Caché Direct の使用法
ユーザ・キャンセル・オプション
3.6.2 IdleHook
ポーリングの読み取り間隔がタイムアウトした場合など、サーバがアイドル状態のときに、サーバ側で処理が行われるよう
に指定するには、このフックを使用します。サーバは、終了確認手順の一環として、このフックを呼び出します。詳細は、
この章の概要にある "サーバの終了確認手順" のセクションを参照してください。
3.6.3 EndTaskHook
サーバが、クライアントから EndTask メッセージを受信したときに実行する必要がある追加処理を指定するには、このフッ
クを使用します。このフックは、任意のアプリケーションのクリーンアップで実行できます。
3.6.4 ShutDownHook
何らかの理由でサーバがシャットダウンされたときに実行する必要がある追加処理を指定するには、このフックを使用し
ます。このフックは、サーバがシャットダウンされるたびに、サーバにより呼び出されます。
この関数は 0 (サーバをシャットダウンするべきではない場合) または 1 (サーバをシャットダウンする必要がある場合) の
どちらかを返します。
3.7 ユーザ・キャンセル・オプション
VisM から Caché にメッセージを送信する場合、サーバによるメッセージ要求の処理に時間がかかり、ユーザが応答を
待たなければならないことがあります。この待機時間が長い場合に、要求をキャンセルするオプションをユーザに提供す
ることができます。これを設定するには、PromptInterval プロパティを使用します。このプロパティは、サーバが応答しな
い場合に、クライアント・アプリケーションが待機する時間 (秒) を表します。この時間が経過すると、ユーザに対してプロ
ンプトが表示されます。このプロンプトは、さらに応答を待つか、操作をキャンセルするかを選択するためのオプションを
ユーザに提供します。MsgText プロパティは、この場合に使用されるメッセージを表す 4 部分で構成される文字列です。
詳細は、"VisM.ocx コントロールの詳細" の章にある "その他の VisM プロパティ" のセクションを参照してください。
Caché Direct の使用法 27
4
最善の使用方法
一般的に、通信および CPU は非常に高速です。特に、タスクが多量にない限り、コンピュータは細かい要求を送信す
る多数のユーザに遅れず対応できます。しかし、クライアント・マシンの負荷は、1 台のクライアントによってのみかかりま
す。一方で、ネットワークおよびサーバ上の負荷は、同時にすべてのクライアントからの蓄積となります。したがって、メッ
セージのトラフィック、サイズ、またはサーバの負荷を少しずつでも増大させるような操作は、全体的なスループットや能
力に多大な影響を及ぼします。以下のいくつかの操作は、このように累積的な負荷を必要最小限に抑えて、スループッ
ト、応答時間、またはシステムの総合的な能力の向上を目指しています。
4.1 必要のないプロパティを削除する
クライアントからサーバに送信される実行メッセージには、必ず、NameSpace、Code、VALUE、P0 ～ P9、PLIST などの
プロパティ用のフィールドが含まれています。NameSpace と Code フィールドは返されるメッセージで削除されますが、
その他のすべてのプロパティについて、変更されたかどうかに関係なく、新しい値が返されます。したがって、メッセージ
のサイズ (および、メッセージの組み立て、送信、および分解にかかる時間) は、全プロパティの現在値の合計サイズに
よって変わります。使用率の高いクライアントが多数ある場合、ネットワーク帯域幅とサーバの能力に及ぶ影響はかなり
大きくなります。
通信が高速で、メッセージが比較的小さくても、大量のメッセージを送信するときに、スピードが問題となる場合は、帯域
幅が消費されないようにメッセージで使用されていないプロパティをすべて削除することをお勧めします。これらの VisM
プロパティはサーバとの通信を目的とするもので、クライアント上での長期保存には効率的ではありません。
また、ミラーリングされたプロパティは、メッセージごとに作成され、破棄されるので、サーバ上でのストレージには使用で
きません。
4.2 アプリケーションをシャットダウンしたときに明示的に切断す
る
影響は小さいですが、サーバから切断せずにクライアントをシャットダウンすると、チャネルで TCP エラーが発生します。
これにより、サーバ・コードで I/O エラーが発生し、これに応答して、サーバ・ジョブがシャットダウンされます (クライアン
トと通信できなくなったサーバはそれ以上使用されないので、これは正しい応答と見なされます)。代わりに、明示的に接
続を切断して、サーバを無理なくシャットダウンできるようにすることをお勧めします。
Caché Direct の使用法 29
最善の使用方法
4.3 再帰的、または非同期的なサーバ呼び出し
各サーバ・チャネルでの通信はすべて同期的に行われます。つまり、あるメッセージが送信され、受信されてから、次の
メッセージが送信される必要があります (この要件は、Caché Direct により強制されています。あるメッセージが保留され
ているときに、別のメッセージを送信しようとすると、エラー条件が返されます)。シングル・スレッド・クライアントとシングル・
サーバの一般的な使用例では多くの場合、これは問題になりません。しかし、この安全性を回避する方法、つまり同期
的に発生しないイベントがあります。タイマ・イベントと、Visual Basic DoEvents() メソッドはその 2 つです。
4.3.1 クライアント上のタイマ
定義により、タイマは非同期イベントです。タイマは、他に行われている処理には干渉しないように設定することができま
す。例えば、進捗状況またはサーバで別のイベントが発生したかどうかを確認するように、タイマをセットアップすることが
可能です。ただし、長い処理を発生させるメッセージをサーバに送信した場合、処理実行中、そのチャネルは使用でき
なくなります。進捗状況を確認する場合、サーバに定期的にコールバックさせて進捗状況を報告させるか、クライアント
から別のチャネルに問い合わせを送信する必要があります。クライアントを独占せずに、長時間にわたるサーバ操作を
実行するには、別のプロセスにジョブを渡して作業を実行させてから、クライアントに戻る方法もあります。このためにチャ
ネルがもう 1 つ必要になることはありませんが、独立したジョブが 1 つ必要になります。メッセージの処理中にタイマが作
動すると、別のメッセージの送信が試みられる可能性があります。この場合、Caché Direct はこのメッセージを受け入れ
ず、“nonsynchronous communication” エラーを返します。
4.3.2 Visual Basic の DoEvents 関数
Visual Basic には、Windows イベント・ループを明示的に呼び出す DoEvents という組み込み関数があります。多くの場
合、他の操作の実行中に、再描画を直ちに実行するために使用されます。あるサーバ・メッセージの処理中に、DoEvents
がサーバ・メッセージを発生させると、危険要因となります。(例えば、DoEvents は、ユーザに別のタスクの継続を許可し
ます。このタスクにより、サーバ・メッセージが発生する可能性があります)。理論上は、これはコールバックでのみ発生し
ます。この場合、新しい再帰的なメッセージがサーバに送信され、元のメッセージのコンテキストを破壊する可能性があ
るため、DoEvents は特に厄介です。ここから先は危険です。原則として、DoEvents を呼び出すコールバックは使用しな
いでください。使用する場合、スタックが完全に戻されるまでユーザ入力を無効にするか、少なくともサーバへの呼び出
しを禁止するためのフラグがアプリケーションに必要です。
30 Caché Direct の使用法
5
VisM.ocx コントロールの詳細
この章では、Caché Direct ActiveX コントロール (VisM.ocx) に関する参考情報について説明します。以下のトピックに
ついて説明します。
•
拡張接続文字列の構文
•
VisM プロパティ
•
VisM メソッド (SetServer()Connect()を含む)
•
VisM イベント
このコントロールは、後述する章で説明する C++ クラスのラッパです。
5.1 VisM 拡張接続文字列の構文
Server プロパティ、Connect() メソッド、および SetServer() メソッドはすべて接続文字列を使用します。接続文字列は、
コロンを区切り文字として使用する、分割化された文字列です。通常、形式は次のとおりです (詳細は、"接続文字列と
接続タグ" で説明しています)。
"CN_IPTCP:server[port]"
この引数の最初にある CN_IPTCP は接続メソッドで、必ず TCP です。2 つ目は Caché スーパーサーバが稼動してい
るサーバの名前、または IP アドレスとポートです。例えば、VisM1 という VisM の接続を設定するには、次の構文を使用
します。
VisM1.Server = "CN_IPTCP:127.0.0.1[57772]"
5.1.1 実行時の接続文字列の形式
これまでの経緯から、接続文字列は、実行時に異なる形式をとる場合があります。具体的に言うと、接続しているときの
接続文字列は奇数個の部分に分割されています。これは、以下のように、Caché Direct により、スーパーサーバ情報の
後に 3 つ目の部分が挿入されるためです。
"CN_IPTCP:server[port]:slaveserver[port]"
この 3 つ目の部分は、接続先のスレーブ・サーバを表します。これはマスタ・サーバの部分の形式と同じです。現在、接
続されていない場合、このプロパティは空です。
Caché Direct の使用法 31
VisM.ocx コントロールの詳細
ユーザ名およびパスワードには、接続文字列内で区切り文字として使用されている文字を使用できません。これには、
コロン (":"、$Piece の区切り文字) と角括弧 ("[" および "]"、ポート番号の区切りに使用される) が含まれます。
5.1.2 その他の接続文字列の形式
接続文字列にはユーザ名とパスワードが含まれることがあります。これらは Caché Direct ログイン・オプションを有効化
している場合にのみ使用されます。このログイン・オプションは Caché セキュリティでは廃止されているので、ここで言及
するだけでマニュアルでは説明していません。
注意
この形式の使用は、お勧めしません。接続文字列にパスワードが含まれている場合、Caché はどのよう
な単純な攻撃でもその影響を受けやすくなります。
接続文字列は、以下のようにユーザ名と暗号化されたパスワードを含むことがあります。
"CN_IPTCP:server[port]:username:password"
この場合、接続されていると、実行時の接続文字列は次の形式になります。
"CN_IPTCP:server[port]:slaveserver[port]:username:password"
接続文字列は、以下のようにユーザ名と暗号化されたパスワードを含むことができます。Caché では、暗号化されていな
い形式のパスワードが必要ですので、バージョン 5.2 以降のサーバに接続している場合は注意してください。
"CN_IPTCP:server[port]:username:@password"
この場合、接続されていると、実行時の接続文字列は次の形式になります。
"CN_IPTCP:server[port]:slaveserver[port]:username:@password"
注釈
クライアントが 5.2 以降の場合、必要に応じて、Kerberos 検証用に Windows 認証情報 (ユーザ名とパスワー
ド) が自動的に使用されます (Kerberos 認証を使用する接続の詳細は、"間接参照を使用した接続" を参照し
てください)。これは、Caché Direct ログインを補足するものです (Direct ログインに代わるものではありません)。
Caché セキュリティがオンになっていない場合、Caché Direct は Kerberos チェックを省略しますが、ユーザ名
とパスワードが指定されていれば、これを渡します。その後、サーバはサーバ側でオンに設定されている操作
を行います。
5.2 VisM プロパティ
VisM コントロールには、サーバでミラーリングされる一連のプロパティと、その他のプロパティがあります。
5.2.1 ミラーリングされた VisM プロパティ
"VisM コントロールの基本" の章にある "ミラーリングされたプロパティ" で説明されているとおり、Caché Direct は、クラ
イアントとサーバの間である特定の VisM プロパティの値をミラーリングします。
これらのプロパティを片方向通信に使用する場合で、特にサイズが大きい場合には、サーバから値を返す前にクリアし
ます。そうしないと、通信リソースは、アプリケーションにより浪費されてしまいます。詳細は、"最善の使用方法" の章を
確認してください。クライアントによりサーバに送信されるその他のプロパティすべてと同様に、その値に使用できるのは、
テキスト文字のみです。前述の章の Unicode とロケールの問題のセクションを参照してください。
32 Caché Direct の使用法
VisM プロパティ
P0、P1、P2、P3、P4、P5、P6、P7、P8、P9
これらのプロパティは、クライアントとサーバでミラーリングされます。クライアントでは、VisM コントロールのプロ
パティとして表示されます。また、サーバでは、ローカル変数として表示され、クライアントにある対応するプロパ
ティと同じ値を持ちます。
PLIST
このプロパティのミラーリング方法は、クライアントとサーバで異なります。クライアントと Caché では、配列の表
現方法が異なるため、Caché Direct はこのプロパティを使用して、サーバとクライアントの間で配列のような値を
受け渡します。このプロパティは、クライアントとサーバでは形式が異なります。詳細は、"VisM コントロールの基
本" の章にある "PLIST の使用" のセクションを参照してください。
VALUE
このプロパティは、P0、P1 などと同じ方法で、クライアントとサーバでミラーリングされますが、Code プロパティ
の値がドル記号または等号で始まっている場合、サーバにより、Code プロパティの先頭に “Set VALUE” また
は “Set VALUE =” が追加されます。つまり、このような場合、結果は VALUE プロパティに返されます。
5.2.2 その他の VisM プロパティ
このセクションでは、その他の VisM プロパティ (ミラーリングされないプロパティ) を一覧表示します。一部のプロパティ
は、サーバに送信されないので注意してください。
Code
実行のためにサーバに送信される ObjectScript コードの行が含まれます。クライアントによりサーバに送信され
る他のすべてのプロパティと同様に、この文字列に使用できるのは、テキスト文字のみです。Unicode とロケー
ルの問題のセクションを参照してください。
ConnectionState
このプロパティは、常に、接続の状態を表しています。これは、キープ・アライブ機能と共に使用され、クライアン
トで通信エラーが発生しているかどうか、発生している場合は、いつ接続が切断されたかをアプリケーションに
通知します。
ConnectionState が 0 の場合、接続には問題がないか、切断が正常に行われています。このプロパティの値
が 0 以外の場合、サーバから切断された時刻 (午前 0 時からの経過秒数) を表しています (これは $Horolog
の秒部分と同じです。日付は示されませんが、最新であると見なされます)。このプロパティは長整数型です。
ConnTag
実行時のみ。この VisM が接続されている CDConnect のタグを表します。このプロパティを変更すると、接続
が変更されるのではなく、関連する CDConnect 自体のタグが変更されます。このプロパティは主に情報提供を
目的としています。ただし、このプロパティが空の文字列である場合、接続されていないか、接続はされていて
もタグは関連付けられていません。
ElapsedTime
最後のメッセージを処理するのに Caché Direct が要した時間を表します。これは、クライアントがメッセージを
送信してから、応答を受信するまでにかかった時間です。実行時、このプロパティは読み取り専用です。
Error
エラー番号が含まれます。0 の場合、エラーは発生していません。実行時、このプロパティは読み取り専用で
す。次の ErrorName プロパティの説明を参照してください。
Caché Direct の使用法 33
VisM.ocx コントロールの詳細
ErrorName
発生したエラーを説明する文字列。空の場合、エラーは発生していません。実行時、このプロパティは読み取り
専用です。
Error および ErrorName プロパティは、サーバ呼び出し後に、必ず設定されます。呼び出しが正常に行われた
場合、Error は 0 に設定され、ErrorName はクリアされます。サーバからエラーが報告された場合、エラー番号
が Error に、簡単な説明が ErrorName に設定されます。これらのエラーには、必ずしも明確な特徴や説明が
含まれているとは限りませんが、それでも、アプリケーションのクライアント部分を使用して、何らかのエラーが発
生しており、対応が必要であることをユーザに通知できます。
このレベルで報告されるエラーは、サーバから通知されるもので、通常は <SYNTAX> や <UNDEFINED> のよ
うなプログラミング・エラーであることに注意してください。アプリケーション・コードから通知された論理エラーや
矛盾などのエラーは、アプリケーションがその結果に入れて報告する必要があります。サーバには、アプリケー
ションが Error および ErrorName プロパティを通じて、エラー状態を返せるようにする機能があります。
ErrorTrap
通信エラーの処理を制御します。Caché Direct アプリケーションで発生する可能性のあるエラーには、通信プ
ロセス自体で発生するエラーと、アプリケーションで発生し、クライアントに報告されるエラーの 2 種類がありま
す。
•
アプリケーション・エラーは、常に、Error および ErrorName プロパティ、および OnError イベントを通じて
報告されます。
•
通信エラーの報告方法は、ErrorTrap の値によって異なります。ErrorTrap が False の場合、通信エラーは
メッセージ・ボックスにより処理され、問題のユーザに警告が伝えられます。ErrorTrap が True の場合、通
信エラーは Error および ErrorName プロパティ、および OnError イベントを通じて報告されます。その後、
ユーザの選択した方法で、アプリケーションによりエラーが処理されます。
これまでの経緯から、ErrorTrap の既定値は False です。通常、VisM から Caché に接続する前に、ErrorTrap
を設定してください。
これが問題になるのは、アプリケーションがユーザなしに実行されている場合、またはこのようなエラーがアプリ
ケーションによって自動的に処理される場合のみです。
ExecFlag
Code プロパティのコードの行をいつ実行するかを制御するスイッチです。既定値は 0 で、これはクライアントが
アイドル状態で、サーバにメッセージを送信していないことを表します。可能な値：
•
ExecFlag が 1 に設定されるとすぐ、サーバは Code プロパティ内のコードを (P0 ～ P9、VALUE、PLIST
プロパティのコンテキストで) 一度実行します。実行を終了したサーバは、ExecFlag を 0 にリセットします
(この設定より、Execute() メソッドのほうがはるかに便利である可能性があります)。
•
ExecFlag が 2 に設定されている場合、“参照時の実行” を意味します。つまり、VALUE プロパティへの参
照の前に必ずサーバへの自動呼出しが行われ、Code プロパティ内のコードが実行されます。これは、Code
プロパティがサーバ上にある何かの現在状態を表す式であり、必要なときにこの式を繰り返し実行したい場
合に役立ちます。例えば、Code プロパティが "=$$GetNext^mydata" である場合、次の Visual Basic コー
ドを使用して、サーバからデータの配列を取得することができます。
For i = 1 to 1000 array(I) = VisM1.VALUE Next i
•
ExecFlag が 3 に設定されている場合、“間隔タイマ作動時の実行” を意味します。この場合、タイマ
(Interval プロパティにより間隔が設定されているもの) が作動すると、Code が実行されます。
通常、タイマ・オプションは、定期的に何かを実行するために使用します。1 つの実行に対して応答するには
Executed イベントを使用します。タイマ・オプションを使用する手順は次のとおりです。
34 Caché Direct の使用法
VisM プロパティ
1. ExecFlag を 0 に設定します。
2. すべての該当するミラーリングされたプロパティ、および Interval プロパティに値を設定します。
3. 次に、ExecFlag に 3 を設定して、タイマをオンにします。
サーバとの通信はすべて同期的であることに注意してください。クライアントは、現在のメッセージに対する応答
を受信してから、次のメッセージを送信する必要があります。タイマを使用すると、クライアントにより、非同期的
にメッセージの送信が試みられることがあります。例えば、タイマにより生成されたメッセージの処理中に、メッ
セージを生成する操作をユーザが実行することがあります。この場合、クライアントには “nonsynchronous message”
エラーが返され、メッセージは送信されません。
Interval
Code プロパティの自動実行の間隔で、単位はミリ秒です。既定値は 1000 ミリ秒 (1 秒) です。詳細は、ExecFlag
プロパティの値 3 を参照してください。
KeepAliveInterval
クライアントから送信される自動キープ・アライブ・メッセージの間隔を整数の秒単位で指定します。これらのメッ
セージは、クライアントがアイドル状態で、間隔に指定された時間が経過した場合に常に送信されます。
KeepAliveTimeOut
サーバへのキープ・アライブ・メッセージの送信後に、クライアントがサーバからの応答を待機する時間を指定し
ます。
LogMask
クライアント側でのデバッグに使用します。これは 32 ビットの整数プロパティで、各ビットは、具体的なログの種
類に対するフラグとして割り当てられています。プロセスの実行中にログがオンになっている場合はいつでも、
実行可能ファイルが実行されているディレクトリにテキスト・ログ・ファイルが作成されます。このファイルの名前は
CDxxx.log で、xxx は次に使用可能な連続番号を表します。先頭の番号は 000 です (したがって、初めてログ
を作成したときのファイル名は CD000.log になります)。プロセスが終了すると、ログは閉じられます。
クライアント側のログを有効化するには、このプロパティの値を 2,147,483,647 (231 – 1) に設定して、すべての
ビットをオンにします。Visual Basic では、&H7FFFFFFF を使用します。これは、同じ数値を 16 進数で表したも
のです。ログをオフにするには、この値に 0 を設定します。
ログの内容の解釈は InterSystems の担当者に任せるのが最善ですが、この内容には VisM で起こったことの
大半のトレースと、サーバとの間で送受信されたメッセージすべてのフル・ダンプが含まれています。情報が少
なすぎる場合よりも、多すぎる場合のほうが失敗する傾向にあります。必要な場合、実際に何が起きたのかをリ
アルタイムに記録したものとして、ログは非常に役に立ちます。
MServer
目的は Server プロパティと同じで、このプロパティに設定できる値のいずれかに設定できます。このプロパティ
は下位互換性のためにのみ提供されているので、新しいアプリケーションでは使用しないでください。詳細は、
付録 "以前のバージョンをお使いの方へのご注意" を参照してください。
MsgText
ユーザにキャンセルするかどうかを確認するときに表示されるメッセージを表す文字列で、4 つの部分に分割さ
れています (PromptInterval プロパティを参照)。このプロパティは次の形式を持つ文字列です。
"prompt_message|title_text|OK_button_text|Cancel_button_text"
Caché Direct の使用法 35
VisM.ocx コントロールの詳細
表示されるメッセージ・ダイアログ・ボックスにはウィンドウ・タイトル (title_text で指定されたもの) と、長いメッセー
ジ (prompt_message で指定されたもの) があります。また、このダイアログ・ボックスにはテキスト・ラベルの付い
た 2 つのボタンが表示されます。
•
OK_button_text というラベルの付いたボタンをクリックすると、このダイアログ・ボックスは閉じられ、クエリは
中断されません。
•
Cancel_button_text というラベルの付いたボタンをクリックすると、このダイアログ・ボックスは閉じられ、クエリ
が中断されます。
このプロパティの既定値は次のとおりです。
"This may take a while. Do you wish to wait?|
Communications|Wait for Reply|Cancel Wait"
このプロパティを設定する場合、どの部分でも省略できます。クライアントでは、文字列で省略された部分、また
は長さ 0 の文字列が設定された部分に対して既定値が使用されます。
Namespace
アプリケーション・コードにより参照されるルーチンやグローバルのネームスペース・コンテキストを作成します。
既定値は空の文字列です。この場合、ルーチンやグローバルは、サーバが実行されているネームスペースで
参照されます。実行メッセージがサーバに到着したときに、NameSpace プロパティが空ではなく、現在のネー
ムスペースとは異なる場合、ネームスペースは指定どおりに変更されます。これはコードの実行前に行われま
す。
ネームスペースを変更するには多大なコストがかかることを覚えておいてください。詳細は、"最善の使用方法"
を参照してください。
PDELIM
PLIST プロパティで使用される区切り文字列。詳細は、ミラーリングされた VisM プロパティのセクションを参照
してください。これは実行時に読み取り/書き込みが行われます。つまり、設計時には設定できません。これまで
の経緯から、既定値は $C(13,10) という文字列となります。空の文字列が設定されている場合、事実上、区切り
文字はなく、PLIST は単一の要素と解釈されます。ただし、このプロパティはサーバに送信されません。
PromptInterval
待機時間を秒単位 (ミリ秒ではありません) で指定します。この時間の経過後、さらに待機するか、操作 (通常
は、時間のかかるクエリ) をキャンセルするかをユーザに尋ねるプロンプトが表示されます。このプロンプトが表
示されるのは、サーバがまだ応答していない場合のみです。このプロンプトは、さらに応答を待つか、操作をキャ
ンセルするかを選択するためのオプションをユーザに提供します。MsgText プロパティは、この場合に表示され
るメッセージの内容を表します。このプロパティが 0 または負の値の場合、プロンプトは表示されません。既定
値は 0 です。
Server
このプロパティの用途は 2 つあります。
•
特定のサーバに接続する場合、または現在接続されているサーバから切断する場合には、このプロパティ
を設定します。
•
実行時に、このプロパティを取得して、クライアントの接続先サーバを確認することができます。この場合、
プロパティの値は多少異なる形式を持ちます。
このプロパティに接続文字列、接続タグ、二重引用符で囲まれた疑問符、または空の文字列を設定できます。
接続文字列の詳細は、この章前半の "VisM 接続文字列" のセクションを参照してください。
36 Caché Direct の使用法
VisM メソッド
Server プロパティを設定することは、SetServer() メソッドの呼び出しと同じ効果があります。詳細は、この章後半
の "接続メソッドの比較" のセクションを参照してください。
Tag
Caché Direct では使用されません。このプロパティは、Microsoft Visual Basic 規約との互換性のために用意さ
れています。これは任意の方法で使用できます。
TimeOut
クライアントがサーバからの応答を待機する時間 (ミリ秒) を表す整数値。これは、TCP 経由でメッセージが送信
された直後から、Windows からデータの受信が報告されるまでの時間です。タイマが作動すると、つまり、許容
時間内に応答が受信されなかった場合、接続は切断されます。これにより、通常はサーバで TCP エラーが発
生し、サーバがシャットダウンされます。クライアントは、処理可能なエラー状態で、制御を取り戻します。アプリ
ケーションが処理の続行を求める場合は、新しい CDConnect を作成する必要があります。これにより、新たに
スレーブ・サーバ・ジョブが作成されます。このジョブはグローバルにはアクセスできますが、古いサーバ・ジョブ
のローカル状態には一切アクセスできません。
このプロパティが負の数または 0 である場合、クライアントは永久にメッセージが返されるのを待ちます。既定値
は 60000 (60 秒) です。
5.3 VisM メソッド
VisM コントロールには、次のメソッドが用意されています。
Connect
この VisM を指定された Caché サーバに接続し、必要に応じて、新しい CDConnect を作成します。以下の構
文のいずれかを使用します。
Connect(connection_string, tag)
Connect(connection_string)
Connect("?", tag)
Connect("?")
Connect(tag)
Connect("")
connection_string
CN_IPTCP:server_name[port] という形式の文字列。ここで、server_name
は Caché が実行されているマシンの DNS 名または IP アドレス、port
は Caché スーパーサーバが使用しているポートです。この章の前半に
ある VisM 接続文字列も参照してください。
tag
新しく作成された CDConnect オブジェクトの名前となるオプションの文
字列。指定されたクライアント・プロセス内で、常にタグの名前が重複し
ないことを確認するのは、ユーザの責任です。
""
この場合、VisM は (該当する場合は、最初の切断後)、最後に開かれた
CDConnect に接続します。元の CDConnect は変更されません。
動作の詳細は、サブセクション "接続メソッドの比較" を参照してください。
DeleteConnection
この VisM に接続されている CDConnect から切断し、これを破棄して、サーバ・ジョブをシャットダウンします。
Caché Direct の使用法 37
VisM.ocx コントロールの詳細
Execute
このメソッドは、Code プロパティを設定し、サーバを呼び出すための近道です。これは、Code プロパティを保
存し、Code プロパティに Execute メソッドへの引数を設定し、実行されるように ExecFlag プロパティを 1 に設
定してから、Code プロパティを呼び出し前の状態に戻すこととまったく同じです。OnError および Executed イ
ベントのエラー・トラップや実行はすべて、同じ方法で行われます。
LoadRtnFromFile
廃止されました。使用しません。
LoadGblFromFile
廃止されました。使用しません。
SetMServer
目的は SetServer() メソッドと同じです。このメソッドは下位互換性のためにのみ提供されているので、新しいア
プリケーションでは使用しないでください。詳細は、付録 "以前のバージョンをお使いの方へのご注意" を参照
してください。
SetServer
この VisM に対する既存の接続を閉じ、指定されたとおりに、新しい接続を作成します。Connect() メソッドとは
対照的に、SetServer() メソッドは既存の CDConnect のチャネルを変更できます。以下の構文のいずれかを使
用します。
SetServer(connection_string, tag)
SetServer(connection_string)
SetServer("?", tag)
SetServer("?")
SetServer(tag)
SetServer("")
connection_string
CN_IPTCP:server_name[port] という形式の文字列。ここで、server_name
は Caché が実行されているマシンの DNS 名または IP アドレス、port
は Caché スーパーサーバが使用しているポートです。この章の前半に
ある VisM 接続文字列も参照してください。
tag
CDConnect オブジェクトの名前となるオプションの文字列。指定されたク
ライアント・プロセス内で、常にタグの名前が重複しないことを確認する
のは、ユーザの責任です。
""
この場合、VisM は CDConnect から切断され、チャネルだけが残ります。
動作の詳細は、次のサブセクション "接続メソッドの比較" を参照してください。
5.3.1 接続メソッドの比較
次のテーブルは、SetServer() メソッドと Connect() メソッドの動作をまとめたものです。
38 Caché Direct の使用法
VisM イベント
最初の引数
SetServer メソッド
接続メソッド
接続文字列
既に接続されているかどうかによって、動
作が異なります。
既に接続されているかどうかによって、動作
が異なります。
•
まだ接続されていない場合、このサー
バに接続します。
•
まだ接続されていない場合、このサーバ
に接続します。
•
既に接続されている場合、CDConnect
のチャネルを変更します (その後、古
いサーバ・プロセスをシャットダウンし
ます)。
•
既に接続されている場合、元の CDConnect から切断し、新しい CDConnect に
接続します (元の CDConnect は変更さ
れません)。
接続タグ
指定された CDConnect に接続します (既
に接続されている場合は、まず切断されま
す。元の CDConnect は変更されません)。
[Caché version 2007.1 以降で可能]
指定された CDConnect に接続します (既に
接続されている場合は、まず切断されます。
元の CDConnect は変更されません)。
空の文字列
CDConnect から切断され、チャネルだけ
が残ります。
最後に開かれた CDConnect に接続します
(既に接続されている場合は、まず切断され
ます。元の CDConnect は変更されません)。
二重引用符で囲まれ
た疑問符
サーバのユーザにプロンプトを表示した後
で、次の処理を行います。
サーバのユーザにプロンプトを表示した後で、
次の処理を行います。
•
まだ接続されていない場合、このサー
バに接続します。
•
まだ接続されていない場合、指定された
サーバに接続します。
•
既に接続されている場合、CDConnect
のチャネルを変更します (その後、古
いサーバ・プロセスをシャットダウンし
ます)。
•
既に接続されている場合、元の CDConnect から切断し、新しい CDConnect に
接続します (元の CDConnect は変更さ
れません)。
Server プロパティを設定することは、SetServer() メソッドの呼び出しと同じ効果があります。
複数の VisM が 1 つの CDConnect を共有している場合は、同時に通信を試みてはなりません。通信しようとした場
合、"nonsynchronous communication" エラー・メッセージが表示されます。
5.4 VisM イベント
Executed
このイベントは、サーバでコードの実行を試行した後に、実行が成功したかどうかに関係なく起動されます。エ
ラーが発生した場合、Executed イベントの前に、OnError イベントが起動されます。
OnError
このイベントは、サーバからクライアントに対してエラーが報告されたとき (つまり、Error および ErrorName プロ
パティに空ではない値が設定されている場合) に、常に起動されます何らかのコードを実行しようとしているとき
にエラーが発生した場合、Executed イベントの前に OnError イベントが起動されます。
Caché Direct の使用法 39
VisM.ocx コントロールの詳細
ShutDown
このイベントは、サーバ・メッセージがタイムアウトした場合、またはサーバが現在シャットダウン処理中であるこ
とを示した場合に起動されます。アプリケーションは、ユーザへの通知、無理のないシャットダウンの実行、また
は再接続の試行のためにこのイベントを使用できます。このイベントへの整数の引数は、ConnectionState プロ
パティの値で、サーバとの接続が失われた時刻を表します。
接続がいったん失われると、その後、メッセージの送信を試みても、<ServerLost> エラーが発生します。
40 Caché Direct の使用法
6
非 ActiveX アプリケーションでの Caché Direct
の使用法
この章では、ActiveX を使用していない (VisM.ocx のない) C++ などのアプリケーションから Caché Direct のプロパティ
やメソッドを使用する方法について説明します。ここでは、読者が他の言語でのプログラミングを十分に理解していること
を前提にしています。
6.1 一般的な手順
全手順は、以下のとおりです。
1. インターシステムズのサポート窓口から Caché Direct のヘッダ・ファイル (.h) を入手します。これらのファイルは、
Caché Direct の機能を提供する C++ クラスを定義します。
2. アプリケーションのソース・コードに、これらのファイルを include します。
3. VisM オブジェクトの機能を再現するには、コードにより、CDLink クラスのインスタンスと、CDParms クラスのインスタ
ンスを作成します。一般に、
•
CDLink には、タイムアウトやエラー・プロパティなどのプロパティや、Caché への接続の管理に使用されるメソッ
ドが含まれます。これらは、VisM コントロールの対応するプロパティと同じです。
•
CDParms には、クライアントからサーバに送信されるプロパティがすべて含まれます。これらのプロパティも、
VisM コントロールの対応するプロパティと同じです。
4. 必要に応じて、プロパティの値を設定し、メソッドを実行します。この場合、VisM コントロールと同じ規則と考慮事項
が適用されます。
6.2 推奨事項
ヘッダ・ファイルには、Caché Direct クラスに関する情報が大量に保管されていますが、これらのクラスがすべて直接的
な使用に適しているわけではありません。まず、CDLink と CDParms クラスのみを使用することをお勧めします。これら
のクラスは下位レベルのクラスの適切なメソッドを公開し、接続が適切に管理されていることを確認します。CDLink およ
び CDParms 以外のクラスは無視してください。
Caché Direct の使用法 41
非 ActiveX アプリケーションでの Caché Direct の使用法
次に、CtrlExec() メソッドではなく、CDLink の CtrlExec1() メソッドの使用をお勧めします。CtrlExec1 メソッドは、ミラーリ
ングされたプロパティのコンテナとして使用される CDParms クラスで使用するように設計されていています。
6.3 メモ
参考までに、Caché Direct クラスの構成を理解しておくと便利です。まず、次の主要なクラスがあります。
•
CDLink クラスはクライアントを表します。VisM コントロールは、このクラスのラッパです。このクラスは、クライアントに
より必要とされる共通プロパティやメソッドを公開します。プロパティには、タイムアウト、コールバック関数ポインタ、
CDMsg オブジェクト、Error、ErrorName、ErrorTrap、キープアライブ、クライアント・タグなどがあります。メソッドに
は、独自のプロパティを管理するメソッドや、必要に応じて作成される CDConnect オブジェクトのメソッドなどがあり
ます。CDLink はそれぞれ、0 個または 1 個の CDConnect にアタッチできます。
•
CDConnect クラスは、このドキュメントの前半で説明したとおり、CDConnect オブジェクトを表します。このクラスに
は、基礎となる通信 DLL (古い NTI DLL、または Kerberos セキュリティを管理する新しい CConnect.dll) へのリン
クが含まれます。また、クライアント側の読み取り/書き込みフックも提供します。実行可能名やシグニチャ、ユーザお
よびクライアント・マシン名など、基本的な一定のクライアント情報はこのクラスに保持されています。また、通信スレッ
ド、タイムアウト、およびキープ・アライブ機能を処理します。さらに、このクラスは、Connect、Send、SendKeepAlive、
Receive、Disconnect などの基本メソッドを提供し、クライアントに対して Server プロパティなどのプロパティを公開
します。また、このサーバが Unicode サーバであるかどうかを公開するほか、サーバのアドレスやポートなどのサー
バ・プロパティも公開します。このクラスには、0 個以上のアタッチされた CDLink クライアントのリストも保持されます。
•
また、適切な形式でメッセージの構成と分解を行う方法を提供する CDMsg というヘルパー・クラスもあります。CDMsg
は、Init、AppendField、GetField などのメソッドを提供します。CDLink には、クライアントからのメッセージを構築す
るための CDMsg が含まれます。また、CDConnect には、Task や KeepAlive メッセージなど、それ自体を構成する
メッセージで使用される CDMsg もあります。
直接アクセスをサポートするために、一部のヘルパー・クラスも用意されています。
•
CDProp クラスは一部のデータ型を定義し、それらに変換メソッドを提供します。これはミラーリングされたプロパティ
を 1 つ表すために使用されます。
•
CDParms クラスは、クライアントがサーバに送信するすべての VisM プロパティ (ミラーリングされたプロパティとその
他、数個のプロパティ) に対するコンテナです。内部的に、このクラスには、CDProp の複数のインスタンスが含まれ
ます。
1 つの CDProp にはプロパティが 1 つ含まれます。CDParms は、1 つのクライアントに対するすべての CDProps のコレ
クションです。
42 Caché Direct の使用法
7
ログ
まれに、特に問題の診断を行うために、クライアントやサーバのログが必要になることがあります。サーバは、エラー・グ
ローバル内にすべてのエラー・トラップも記録します。
7.1 クライアントでのログ
一般に次の 2 つの方法で、クライアントでログを有効にできます。
•
VisM.ocx の LogMask プロパティを設定する。このプロパティは、レジストリ設定をすべてオーバーライドします。
•
レジストリ・スイッチを設定する。レジストリ設定は、プロパティが設定されていない場合の既定値の役割を果たしま
す。レジストリ・スイッチにより、どのクライアント・プロセスでログを作成するかを正確に制御することができます。具体
的に言うと、これらのスイッチは、HKEY_CURRENT_USER ハイブ、または HKEY_LOCAL_MACHINE ハイブに常駐
可能で、特定のユーザ、またはアプリケーション・プログラム、もしくはこれらの組み合わせに対してのみ、ログが記
録されるように変更できます。選択肢は最も具体的なものから最も一般的なものに向かって階層的に検索されるの
で、特定の目的のための具体的なスイッチにより、一般的なスイッチがオーバーライドされることがあります。
また、Caché Direct には、これらのレジストリ・エントリを設定、取得するためのルーチンが用意されているため、プロ
グラムの制御下で簡単に操作できます。
7.1.1 VisM LogMask プロパティ
VisM.ocx の LogMask プロパティを直接設定できます。ログを有効にするには、このプロパティを 0x7FFFFFFF (C++ の
場合)、または &H7FFFFFFF (Visual Basic の場合) に設定します。以下はその例です。
VisM1.LogMask = Val(&H7FFFFFFF)
この 16 進数値に対応する 10 進数の整数は、2147483647 です。
ログを無効にするには、このプロパティを 0 に設定します。このプロパティは、レジストリ設定をすべてオーバーライドしま
す。
7.1.2 レジストリ・スイッチ
クライアント・ログ・スイッチはレジストリ・キー値で、次の名前を持ちます。
•
LogMask はビット・マスクで、ログ記録を行うかどうかを表します。前のセクション "VisM LogMask プロパティ" で説
明した LogMask プロパティと同じ値を取ります。
Caché Direct の使用法 43
ログ
•
LogFolder は特定のフォルダにログ・ファイルを保存する場合に使用します。既定では、アプリケーションのメインの
実行可能ファイルが保存されているフォルダに保存されます。値が指定されていない場合、または空の場合は、既
定値が使用されます。この章の後半にある "ログ・ファイルのサイズの制限" も参照してください。
スイッチは、hivename/Software/InterSystems/Cache キーの下にあります。ここで、hivename は次のどちらかです。
•
HKCU (HKEY_CURRENT_USER ハイブ)
•
HKLM (HKEY_LOCAL_MACHINE ハイブ)
また、指定されたアプリケーションを実行している特定のユーザの場合は、さらに 3 種類の値を使用できます。これらの
値には、ユーザまたはアプリケーション名と基本値名を連結した名前が付けられます。例えば、ユーザ名が Joeで、ア
プリケーション名が MyApp.exe の場合、LogMaskJoeMyApp、LogMaskJoe、および LogMaskMyApp という 3 つの
値も使用できます。これらの値はこの順にチェックされます。それぞれの値はまず、HKCU でチェックされ、次に HKLM
でチェックされます。最初に見つかったものが使用されます。同様に、LogFolderJoeMyApp、LogFolderJoe、
LogFolderMyApp という名前の値が使われることもあります。
7.1.3 レジストリ値の取得と設定
これらのレジストリ値を設定し、取得するために使用できるクライアント側ルーチンは 4 種類あります。これらのルーチン
は、ISLog.dll ファイルに公開されています。これらの C シグニチャは次のとおりです。
DWORD GetRegLogMaskEx(LPCSTR pUsername, LPCSTR pAppname);
DWORD SetRegLogMaskEx(HKEY hiveKey,
LPCSTR pUsername,
LPCSTR pAppname,
DWORD dwMask);
int GetRegLogFolderEx(LPCSTR pUsername,
LPCSTR pAppname,
LPSTR buf,
int buflen);
void SetRegLogFolderEx(HKEY hiveKey,
LPCSTR pUsername,
LPCSTR pAppname,
LPSTR buf);
いずれの場合も、pUsername または pAppname が NULL または空の文字列である場合、これらの引数は使用されませ
ん。これらの引数が指定された場合、Get_ routines は適切な組み合わせを検索し、最初に見つかったものがあれば、そ
れを返します。
例えば、GetRegLogMaskEx(NULL, “Joe”, NULL) を呼び出した場合、最初に、HKCU と HKLM から LogMaskJoe が
検索され、次に、HKCU と HKLM から LogMask が検索され、最初に見つかったものが返されます。何も見つからなかっ
た場合は 0 が返されます。pUsername と pAppname の両方が指定されている場合、4 つの組み合わせがすべて、上記
の順序で検索されます。
SetRegLogMaskEx および SetRegLogFolderEx ルーチンでは、HKCU または HKLM が最初の引数に指定されている場
合、そのハイブが設定されます。ハイブが指定されていない場合、既定値の HKLM が設定されます。
SetRegLogMaskEx は現在設定しているキーに直前に設定されていた値を返します。
GetRegLogFolderEx は見つかったフォルダ名の長さを返します。見つからなかった場合は、0 を返します。
7.1.4 ログ・ファイルのサイズの制限
2 種類のクライアント側レジストリ設定 (LogSizeLimit) を使用して、ログ・ファイルが大きくなりすぎるのを防ぐことができま
す。スイッチは、HK/Software/InterSystems/Cache キーの下にあります。前述のとおり、HK は HKCU または HKLM
のどちらかです。
44 Caché Direct の使用法
サーバでのログ
この設定は、クライアントがログに書き込みしている間のログ・ファイルの最大サイズを表します。ログの大きさがこのサイ
ズに達すると、クライアントは、新しいログ・ファイルへの書き込みを開始します。古いログ・ファイルが既にある場合、この
ファイルは破棄されるので、一度に 3 つ以上のログ・ファイルが存在することはありません。クライアントがシャットダウンさ
れると、既存の 2 つのログ・ファイルは結合されます。結果として得られるログのサイズの上限は、LogSizeLimit の値の
2 倍で、この値を超えることはありません。
ログ・ファイルは、セッションに関する基本情報から始まり、その後に文字列 Snip というラベルの付いた区切り文字、ロ
グに記録された最新のアクティビティが続きます。
7.2 サーバでのログ
サーバでのログを有効化すると、クライアントとサーバの間で送受信されたメッセージすべてを含め、スレーブ・サーバ・
ジョブのサーバ部分で行われたアクティビティのトレースがログに記録されます。サーバでのログを有効化するには、
Caché ターミナルを使用して、次のコマンドを入力します。
Set ^%CDLOG=1
ログを有効にした後に開始された新しい Caché Direct サーバ・ジョブは、通常、mgr ディレクトリに CDxxx.log という名前
のテキスト形式のログ・ファイルを作成します。ここで、xxx には、このログの対象となるジョブの $Job が入ります。新しい
ジョブはそれぞれ、専用のログ・ファイルを持ちます。スイッチがオンになったら、必要なテストを実行してください。
スイッチは、スレーブ・サーバ・ジョブが開始されたときにのみチェックされます。その後、スイッチを変更しても、既に実行
されているジョブには影響はありません。したがって、ジョブの開始後、ログをオンまたはオフにすることはできません。
テストが終了したら (または、少なくとも開始されたときに)、空の文字列を設定するか、強制終了してスイッチをオフにし
ます。
Kill ^%CDLOG
注意
このスイッチはグローバルで、すべての新規ジョブに影響を与えます。また、このログは非常に大きくな
る可能性があります。したがって、ログはできるだけ短時間で実行することをお勧めします。特にサーバ
がテスト専用ではない場合は、できるだけ短くしてください。クライアントからプロセスを自動化して、テス
ト自体が開始される直前にスイッチをオンにする Caché Direct ジョブ、およびテストの開始直後にスイッ
チをオフにするジョブを実行することができます。これをテスト自体の一部にして、スイッチを設定し、
Server プロパティをリセットして再接続してから (これにより、新しいサーバ・ジョブが開始されます)、再
接続後の最初のアクティビティとしてスイッチをオフにすることも可能です。例えば、クライアントが Visual
Basic アプリケーションである場合、次のようなコードで始めることができます。
VisM1.Execute "Set ^%CDLOG=1"
; reset to the same value as before then start a new job
VisM1.Server = VisM1.Server
VisM1.Execute "Kill ^%CDLOG"
7.3 サーバ・エラー・グローバル
前述のサーバ・ログとは別に、サーバは、グローバル %CDServer("Error") に内部サーバ・エラー・ログを記録していま
す。これにはトラップされたエラーがすべて記録されます。
このログに “emergency brake” という行が含まれている場合、これはサーバにより、エラーの無限ループ (1 秒間に 5
回以上のエラー) が検出されたことを表しています。
Caché Direct の使用法 45
A
インストールとアップグレード
Caché をインストールすると、Caché Direct も自動的にインストールされます。しかし、場合によっては、Caché を再イン
ストールせずにサーバをアップグレードするか、Caché がインストールされていないマシンにクライアント側ソフトウェアを
インストールする必要がある場合もあります。この付録では、これらの操作を行う方法について説明します。
A.1 Caché Direct サーバのアップグレード
Caché Direct では、Caché インストールの残りの部分と共に自動的にインストールされたサーバが使用されていますが、
新しい Caché をインストールしなくても、このサーバを簡単にアップグレードできます。Caché Direct サーバ・コードは古
いクライアントやプラットフォームとの下位互換性を保つように構築されています。つまり、問題を修正するためにCaché
Direct サーバをアップグレードするか、他の大規模なアップグレードを実行せずに新しい機能をインストールできるとい
うことです。
Caché Direct サーバをアップグレードするには、次の操作を行います。
1. インターシステムズのサポート窓口から、使用しているプラットフォームに対応する最新の Caché Direct の暗号化さ
れたテキスト・ファイルを取得し、Caché サーバ・マシンに保存します。このファイルの拡張子は .enc です。
2. 実行中の Caché Direct ジョブをすべて停止します。
3. ターミナルで、以下のコマンドを入力します。
Do rload^%CDCrypt(<path_to_.enc file>[,password])
例：
Do rload^%CDCrypt("C:\\temp\\CDCache.enc","SYS")
これにより、ソースが解読され、結果として得られた .int コードがロードされてコンパイルされた後、このソースが破棄され
ます。サーバ・ソースを保存する場合は、オプションのパスワードを設定します。通常、これは省略されます。正しいパス
ワードを入力した場合、.int ソースはそのまま保持されます。変更のデバッグやテストなど、ソースを必要とするアクティビ
ティを実行する必要がある場合は、インターシステムズのサポート窓口からパスワードを入手できます。
A.2 新規マシンへの VisM のインストール
VisM をインストールする最も簡単な方法は、通常どおり、Caché クライアント・ソフトウェアをインストールすることです。し
かし、Caché Direct クライアント・ソフトウェアを手動でインストールできます。そのためには、以下の操作を実行します。
Caché Direct の使用法 47
インストールとアップグレード
1. Microsoft Visual 2008 Redistributable Package が既にインストールされていることを確認します。VisM DLL を登録
するには、このパッケージが必要です。
2. クライアントがインストールされているマシンから、次のファイルをコピーします。
Caché Direct 5.1 またはそれ以降の場合
Caché Direct バージョン 5.1 以前の場合
•
cconnect.dll
•
NTI.dll
•
Cmvism32.dll および同様の名前を持つファイルすべ
て
•
NTIIPTCP.dll
•
•
ISCDLink.dll
Cmvism32.dll および同様の名前を持つファイ
ルすべて
•
ISLog.dll
•
ISLog.dll
•
VISM.ocx
•
VISM.ocx
ディレクトリ C:\Program Files\Common Files\InterSystems\Cache からファイルをコピーし、ターゲット・マシンの
同じディレクトリに貼り付けます。
3. DOS プロンプトを開き、このディレクトリに移動して、次のコマンドを入力して、ActiveX コントロールを登録します。
regsvr32 vism.ocx
48 Caché Direct の使用法
B
以前のバージョンをお使いの方へのご注意
Caché Direct は、下位互換性を持つように設計されていますが、場合によっては動作が変更することがあります。アーキ
テクチャの変更の中には、以前のバージョンをお使いの方に特にお知らせしておきたいものが含まれています。この情
報は、新しい機能を活用できるようにアプリケーションを順応させる場合に役立ちます。
B.1 Caché Direct での IPv6 に関する問題
Caché Direct の現在のリリースでは、IPv6 のアドレス形式が全面的にサポートされています。特に、VisM.ocx の
Server/MServer プロパティにより、以前と同じ一般的な接続文字列形式で IPv6 アドレスを使用できます。
ただし、アプリケーションで使用している方法によっては、不可避な障害が発生することも考えられます。具体的には、
Caché Direct の接続文字列は、以下の一般的な形式のコロン区切り表現となっています。
CN_IPTCP:server_address[port]
server_address はマスタ・サーバで、これには IP アドレス、サーバの DNS 名、または特別な名前 localhost を指定で
きます。
Server プロパティ (指定されたサーバへの接続を要求するメカニズム) の設定から戻ると、接続を試みた結果を反映し
てこのプロパティは再設定されます。接続に成功していると、スレーブ・サーバ・アドレスを指定した最後の部分が追加さ
れます。最近のリリース (スーパーサーバの導入以降) では、この部分は必ず 2 番目の部分と同じになるので重複した
指定となります。接続に失敗していると、プロパティの値は空の文字列 "" に変更されます。
server_address でコロンを使用する IPv6 アドレスでは、混乱が発生する可能性があります。IPv6 では、複数のループ
バック・アドレス形式を使用できます。Caché Direct では、これらすべての形式をサポートしています。ただし、アプリケー
ション・コードで設定した前提条件によっては、新しいアドレスを使用すると不適切な動作になる可能性があります。以下
では、Caché Direct で IPv6 アドレスがどのように扱われるかについて説明します。
1. 接続文字列は、上記と同じ一般的な形式です。これは、ポート番号を囲む角括弧を検索することによって、
server_address のエクステントを認識します。
2. IPv6 は独自のループバック形式 (::1) を持ち、IPv4 スタイルおよび “射影 IPv4” アドレス形式もサポートします。
これらは ::a.b.c.d および ::FFFF.a.b.c.d のようになります。ここで a.b.c.d は IPv4 アドレスの 10 進バイ
ト、FFFF はすべて 1 の 2 バイト・シーケンスです。したがって、IPv4 のループバック
は、::127.0.0.1、::FFFF.127.0.0.1、::FFFF:007F:0100 のように、アドレスの下位バイトから順に記述し
て表現できます。これらのループバックはすべて同等で、実際のアドレスを表すものではありません。意味のある比
較を行うため、Caché Direct では、これらすべてのアドレスを、接続ソフトウェアで認識して適切に処理できる名前
localhost に変換します。これは、そのアドレスがレジストリから取得したものであるか、明示的にアプリケーション・
コードから取得したものであるかには関係ありません。
Caché Direct の使用法 49
以前のバージョンをお使いの方へのご注意
3. Caché Direct では、アドレスが IPv6 形式 (コロンを使用した形式) の場合、3 番目の部分が接続文字列に付加され
なくなりました。接続に成功すると、Server プロパティは接続先のサーバを表す値に設定されます。IPv6 形式のア
ドレスの場合は、指定した文字列を簡潔にしたような形式になります。IPv4、DNS 名、または localhost を使用し
ている場合は、5.1 以前の Caché のバージョンとの後方互換性を維持するため、重複指定となる 3 番目の部分が
引き続き使用されます。
4. IPv6 環境での区切り文字としてコロンのみを扱うアプリケーション・コードは適切に機能しない可能性があります。
一般的な考え方として、接続文字列が意味する内容を人間が容易に認識できれば、ソフトウェアでも容易に認識できま
す。接続文字列の解析ルールは以下のとおりです。
1. 最初の部分は必ず CN_IPTCP: と同じになります。
2. 次の部分 (IPv4 形式または IPv6 形式ではサーバとポート) は、ポート番号の後の閉じ角括弧で終了します。これに
より、アドレスにあるコロンにより生じる混乱を避けることができます。
3. Cache セキュリティの導入により、ユーザ名とパスワードは接続文字列では指定しないようになりました。ただし、Caché
Direct ではどちらのパラメータも、拡張した IPv6 形式で引き続き正しく認識および処理できます。
B.2 以前の共有接続の動作
従来の VisM コントロールは、シングル・スレッドの共有接続メカニズムでした。これは、プロセス中に VisM コントロール
すべてで共有される MServer プロパティを持っていました。実際、このプロパティは、サーバへの接続を反映した計算
値でした。VisM で変更すると、このプロパティは現在のサーバから切断され、新しいサーバ・プロセスへの新しい接続が
作成されます。このプロパティに空の文字列が設定されている場合、サーバから切断されます。
通信は、別のスレッドで行われました。
B.3 新しいアーキテクチャ
新しい VisM コントロールの新しい内部構造は、VisM オブジェクト、これらが接続されている CDConnects、およびその
下で CDConnects にアタッチされているサーバ・プロセスの 3 層から構成されています。CDConnect には、特にこの説
明に関連する次のような性質があります。
•
CDConnect は、複数の呼び出し元に接続できます。これは、複数の VisM クライアントが同じサーバ・プロセスを共
有できることを示します。
•
CDConnect をあるサーバ・プロセスから切断し、すべての呼び出し元と共に別のサーバ・プロセスに接続することが
できます。
•
CDConnect をサーバ・プロセスに接続する必要はありません。
•
CDConnects は複数存在することがあります。これらの CDConnects はそれぞれ、専用のサーバと VisM クライアン
トを持ちます。
現在の 3 層と、CDConnect 層の設計方法により、Caché Direct アプリケーションの柔軟性はさらに高まっています。こ
れまでは不可能だったクライアント/サーバ関係を作成できます。また、同時に別々の接続が可能なので、マルチスレッ
ド・アプリケーションを作成できます。接続はそれぞれ、独立した通信スレッドを持ち、これを管理します。それでも、各接
続の同期がとられている必要があります。これは、サーバ・ジョブ自体はシングルスレッドで、一度に処理できるメッセー
ジは 1 つのみだからです。
50 Caché Direct の使用法
動作に関する注意
B.4 動作に関する注意
ここで説明する変更により、下位互換性の問題が発生する場合があります。新しい VisM は、ほとんどの一般的な場合
と同じ動作を試みます。それができない場合、最も予期される動作を試みます。
このバージョンの VisM には、Server というプロパティがあり、これはCaché への接続に使用されます。下位互換性のた
めに、VisM には、古い名前の MServer というプロパティもあります。ほとんどの場合、どちらのプロパティでも使用でき
ますが、VisM コントロールがサーバに接続されていない場合は、プロパティによって動作が異なります。
•
アプリケーションが MServer プロパティを取得していても、VisM はまだ接続されていないという場合、最新の接続
が存在する場合にはこれを共有し、その接続をMServer プロパティとして返します。
•
同じ状況で、アプリケーションが Server プロパティを取得した場合、VisM は接続されず、Server プロパティは空の
文字列のまま残ります。
アプリケーションで Server プロパティまたは MServer プロパティが設定されている場合の動作は次のとおりです。
•
VisM が接続されていなかった場合、新しい接続が作成されます。既存の VisM やその接続には影響はありません。
この動作は、Caché Direct の前のバージョンの動作とは異なります。
•
VisM が接続されていた場合、VisM が使用している (他の VisM と共有している可能性のある) 接続オブジェクトが
サーバから切断されます。接続文字列が空ではない場合、新しいサーバに接続されます。この影響を受けるのは、
このチャネルを共有している VisM のみです。これは、他の VisM すべてのサーバを変更する、Caché Direct の従
来のバージョンとの互換性を持ちます。
また、このバージョンの VisM には新しいメソッドも用意されています。詳細は、"VisM コントロールの使用に関する基本"
の章を参照してください。これらのメソッドは、Connect()、SetServer()、および DeleteConnection() です。
Caché バージョン 2007.1 以降、SetServer() の最初の引数として、接続タグを使用できるようになりました。また、Server
プロパティ (または、MServer プロパティ) に接続タグを設定することもできます。
B.5 その他のアーキテクチャの変更
•
このバージョンから、Caché スーパーサーバが従来の Caché Direct マスタ・サーバ・ルーチンに取って代わります。
従来、マスタ・サーバは接続から要求を受信し、新しいポートにスレーブ・サーバ・プロセスを生成し、呼び出し元を
新しいポートにリダイレクトしていました。呼び出し元はマスタ・サーバから切断され、正しいポート上のスレーブ・サー
バに接続されました。
今バージョンから、スーパーサーバは接続要求を受信し、スレーブ・サーバ・プロセスを生成してから、途中で切断
されずに、呼び出し元を直接このプロセスに転送します。その他のポートは使用されません。
•
Caché Direct サーバが Unicode サーバの場合、メッセージはすべて Unicode で送信されるため、ロケールの問題
が解消されます (ただし、これは 8 ビット・サーバには当てはまりません。詳細は、"Unicode とロケールの問題" を参
照してください)。
•
使用している Caché Direct のバージョンによっては、メッセージの処理や、クライアントとサーバの相互作用の制御
などを行うフックが追加されていることもあります。
•
Caché Direct では、Caché セキュリティが透過的にサポートされるようになったため、NewTask 処理にログイン・フッ
ク (^%CDSwitch("SecHook")) はほとんど必要なくなりました。このフックは引き続きサポートされますが、マニュアル
には記載されません。
Caché Direct の使用法 51
C
例： Visual Basic でのプリンタのサポート
インターシステムズは、Caché ObjectScript から Windows の既定のプリンタ (VB Printer オブジェクト) を使用したコール
バックの例を示す Caché Direct サンプルを提供できます。このサンプルの副産物として、Visual Basic フォームが 1 つ
提供されますが、このフォームはどのようなプロジェクトにでも組み入れることができ、必要に応じて使用または拡張でき
ます。また、Screen や Clipboard などの Visual Basic オブジェクトをサポートするように拡張することも簡単にできます。
このサンプル・ルーチンは、それ自体を Windows の既定のプリンタに出力します。このとき数種類のフォントが使用され、
コメントは斜体で、ページのヘッダと数値は異なるフォントで印刷されます。このルーチンの記述は非常に単純で、必要
となる印刷機能のほとんどが含まれています。印刷モデルは Visual Basic (および Windows) のモデルです。Caché の
モデルではありません (Write コマンドへのスラッシュ・パラメータをカスタム GBI デバイスに実装できますが、このサンプ
ルより機能が優れていることも、便利なこともありません。Caché 規則に対して1 つ妥協されているのは、Caché ObjectScript
モデルが後に続く、Print メソッドのパラメータです。このほうが簡単で馴染みある方法となるためです。Print() メソッドへ
の引数は二重引用符で囲まれた文字列となることに注意してください。これは、ObjectScript 変数の名前は、Basic に
とって何の意味もないからです。
C.1 概要
一般に、Caché ObjectScript ルーチンから Basic コードを実行するには、このコードをボタンの Click イベントに配置し
て、このボタンの Value プロパティを 1 に設定します。これにより、Click イベントが起動され、Basic コードが実行される
ようになります。このバリエーションとして、他のアクションに応じて起動される他のイベントがあるという事実を活用できま
す。特に、テキスト・コントロールは、Text プロパティへの変更に対応して Change イベントを起動します。これにより、
Caché からの呼び出し 1 回で、Text プロパティに適切な文字列を設定し、Change イベント・コードにこれを解析させる
ことができるので便利です。結果がある場合、同じテキスト・コントロールの Tag プロパティに返されます。このアプローチ
は、まったく一般的な方法で、独立した隠しフォームで使用できます。また、すべて Basic で記述されます。
C.2 内部コマンドの構文
サンプルには、コマンド文字列を書式設定し、これをプリンタ・オブジェクトに送信するための簡単な ObjectScript ルー
チンがいくつか含まれています。Text プロパティには、コマンドと数個の引数から構成される文字列が含まれます。この
コマンドは、Printer オブジェクトを使って実行される、プロパティの設定や取得、メソッドの実行などの操作に対応しま
す。
Caché Direct の使用法 53
例： Visual Basic でのプリンタのサポート
C.2.1 プロパティの設定
プロパティを設定するには、SetProp() の後に、property_name=value の形式で 1 つ以上のプロパティ名と値のペアをコ
ンマで区切って指定します。これにより、1 つの呼び出しで、複数のプロパティを設定できます。例えば、Printer1 インス
タンスに直接アクセスするには、次のようにします。
Set _Printer1!txtPrint.Text="SetProp:FontName=Arial,FontSize=12,FontBold=1"
また、ヘルパー・ルーチンを通じてプリンタにアクセスするには、次のようにします。
Do SetProp^%CDPrt("FontName=Arial,FontSize=12,FontBold=1")
C.2.2 プロパティの取得
プロパティの値を取得するには、GetProp()の後に、コンマで区切ったプロパティ名を指定します。このクエリに対する応
答は、Tag プロパティに、SetProp() 引数と同じ形式で設定されます。例えば、プリンタに直接アクセスするには、次のよ
うにします。
Set _Printer1!txtPrint.Text="GetProp:FontName,FontSize,FontBold"
また、ヘルパー・ルーチンを通じてプリンタにアクセスするには、次のようにします。
Set prop=$$GetProp^%CDPrint("FontName,FontSize,FontBold")
その後、Tag プロパティに、次の形式の文字列が設定されます。
"FontName=Arial,FontSize=12,FontBold=1"
このプロパティは、関数の結果としても返されます。
C.2.3 メソッドの実行
このサンプルで使えるメソッドは、NewPage()、Scale()、TextHeight()、TextWidth()、Print()、および EndDoc() です。これ
らのメソッドにはそれぞれ、ヘルパー・ルーチンを通じて実行可能な同等のコマンドがあります。
Print() メソッドの引数は、Basic の規約ではなく、Write コマンドと同様、Caché ObjectScript 形式制御規約に従って指
定します。例えば、プリンタに直接アクセスするには、次のようにします。
Set
Set
Set
Set
Set
Set
_Printer1!txtPrint.Text="NewPage"
_Printer1!txtPrint.Text="Scale:0,0,80,60" or "Scale"
_Printer1!txtPrint.Text="TextHeight:"12""
_Printer1!txtPrint.Text="TextWidth:"50""
_Printer1!txtPrint.Text="Print:!,?8,""Some text"""
_Printer1!txtPrint.Text="EndDoc"
ヘルパー・ルーチンを通じてプリンタにアクセスするには、次のようにします。
Do NewPage^%CDPrint
Do Scale^%CDPrint(0,0,80,60) or Do Scale^%CDPrint( )
Set ht=TextHeight^%CDPrint("12")
Set wid=TextWidth^%CDPrint("50")
Do Print^%CDPrint("!,?8,""Some text""")
Do EndDoc^%CDPrint
Print() メソッドへの引数は二重引用符で囲まれた文字列にする必要があります。これは、Caché ObjectScript 変数の名
前は、Basic にとって何の意味もないからです。内部引用を二重にして、適切に文字列を引用しているルーチンについ
ては、サンプル・コードの quote^CDPrTest を参照してください。
54 Caché Direct の使用法

Download Report