VisM.ocx コントロールの詳細

これらのプロパティは、クライアントとサーバでミラーリングされます。クライアントでは、VisM コントロールのプロパティとして表示されます。また、サーバでは、ローカル変数として表示され、クライアントにある対応するプロパティと同じ値を持ちます。

このプロパティのミラーリング方法は、クライアントとサーバで異なります。クライアントと Caché では、配列の表現方法が異なるため、Caché Direct はこのプロパティを使用して、サーバとクライアントの間で配列のような値を受け渡します。このプロパティは、クライアントとサーバでは形式が異なります。詳細は、"VisM コントロールの基本" の章にある "PLIST の使用" のセクションを参照してください。

このプロパティは、P0、P1 などと同じ方法で、クライアントとサーバでミラーリングされますが、Code プロパティの値がドル記号または等号で始まっている場合、サーバにより、Code プロパティの先頭に “Set VALUE” または “Set VALUE =” が追加されます。つまり、このような場合、結果は VALUE プロパティに返されます。

実行のためにサーバに送信される ObjectScript コードの行が含まれます。クライアントによりサーバに送信される他のすべてのプロパティと同様に、この文字列に使用できるのは、テキスト文字のみです。Unicode とロケールの問題 のセクションを参照してください。

このプロパティは、常に、接続の状態を表しています。これは、キープ・アライブ機能と共に使用され、クライアントで通信エラーが発生しているかどうか、発生している場合は、いつ接続が切断されたかをアプリケーションに通知します。

ConnectionState が 0 の場合、接続には問題がないか、切断が正常に行われています。このプロパティの値が 0 以外の場合、サーバから切断された時刻 (午前 0 時からの経過秒数) を表しています (これは $Horolog の秒部分と同じです。日付は示されませんが、最新であると見なされます)。このプロパティは長整数型です。

実行時のみ。この VisM が接続されている CDConnect のタグを表します。このプロパティを変更すると、接続が変更されるのではなく、関連する CDConnect 自体のタグが変更されます。このプロパティは主に情報提供を目的としています。ただし、このプロパティが空の文字列である場合、接続されていないか、接続はされていてもタグは関連付けられていません。

最後のメッセージを処理するのに Caché Direct が要した時間を表します。これは、クライアントがメッセージを送信してから、応答を受信するまでにかかった時間です。実行時、このプロパティは読み取り専用です。

エラー番号が含まれます。0 の場合、エラーは発生していません。実行時、このプロパティは読み取り専用です。次の ErrorName プロパティの説明を参照してください。

発生したエラーを説明する文字列。空の場合、エラーは発生していません。実行時、このプロパティは読み取り専用です。

Error および ErrorName プロパティは、サーバ呼び出し後に、必ず設定されます。呼び出しが正常に行われた場合、Error は 0 に設定され、ErrorName はクリアされます。サーバからエラーが報告された場合、エラー番号が Error に、簡単な説明が ErrorName に設定されます。これらのエラーには、必ずしも明確な特徴や説明が含まれているとは限りませんが、それでも、アプリケーションのクライアント部分を使用して、何らかのエラーが発生しており、対応が必要であることをユーザに通知できます。

このレベルで報告されるエラーは、サーバから通知されるもので、通常は <SYNTAX> や <UNDEFINED> のようなプログラミング・エラーであることに注意してください。アプリケーション・コードから通知された論理エラーや矛盾などのエラーは、アプリケーションがその結果に入れて報告する必要があります。サーバには、アプリケーションが Error および ErrorName プロパティを通じて、エラー状態を返せるようにする機能があります。

通信エラーの処理を制御します。Caché Direct アプリケーションで発生する可能性のあるエラーには、通信プロセス自体で発生するエラーと、アプリケーションで発生し、クライアントに報告されるエラーの 2 種類があります。

• アプリケーション・エラーは、常に、Error および ErrorName プロパティ、および OnError イベントを通じて報告されます。

• 通信エラーの報告方法は、ErrorTrap の値によって異なります。ErrorTrap が False の場合、通信エラーはメッセージ・ボックスにより処理され、問題のユーザに警告が伝えられます。ErrorTrap が True の場合、通信エラーは Error および ErrorName プロパティ、および OnError イベントを通じて報告されます。その後、ユーザの選択した方法で、アプリケーションによりエラーが処理されます。

これまでの経緯から、ErrorTrap の既定値は False です。通常、VisM から Caché に接続する前に、ErrorTrap を True に設定してください。

これが問題になるのは、アプリケーションがユーザなしに実行されている場合、またはこのようなエラーがアプリケーションによって自動的に処理される場合のみです。

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 イベントを使用します。タイマ・オプションを使用する手順は次のとおりです。

1. ExecFlag を 0 に設定します。

2. すべての該当するミラーリングされたプロパティ、および Interval プロパティに値を設定します。

3. 次に、ExecFlag に 3 を設定して、タイマをオンにします。

サーバとの通信はすべて同期的であることに注意してください。クライアントは、現在のメッセージに対する応答を受信してから、次のメッセージを送信する必要があります。タイマを使用すると、クライアントにより、非同期的にメッセージの送信が試みられることがあります。例えば、タイマにより生成されたメッセージの処理中に、メッセージを生成する操作をユーザが実行することがあります。この場合、クライアントには “nonsynchronous message” エラーが返され、メッセージは送信されません。

Code プロパティの自動実行の間隔で、単位はミリ秒です。既定値は 1000 ミリ秒 (1 秒) です。詳細は、ExecFlag プロパティの値 3 を参照してください。

クライアントから送信される自動キープ・アライブ・メッセージの間隔を整数の秒単位で指定します。これらのメッセージは、クライアントがアイドル状態で、間隔に指定された時間が経過した場合に常に送信されます。

サーバへのキープ・アライブ・メッセージの送信後に、クライアントがサーバからの応答を待機する時間を指定します。

クライアント側でのデバッグに使用します。これは 32 ビットの整数プロパティで、各ビットは、具体的なログの種類に対するフラグとして割り当てられています。 プロセスの実行中にログがオンになっている場合はいつでも、実行可能ファイルが実行されているディレクトリにテキスト・ログ・ファイルが作成されます。このファイルの名前は CDxxx.log で、xxx は次に使用可能な連続番号を表します。先頭の番号は 000 です (したがって、初めてログを作成したときのファイル名は CD000.log になります)。プロセスが終了すると、ログは閉じられます。

クライアント側のログを有効化するには、このプロパティの値を 2,147,483,647 (231 – 1) に設定して、すべてのビットをオンにします。Visual Basic では、&H7FFFFFFF を使用します。これは、同じ数値を 16 進数で表したものです。ログをオフにするには、この値に 0 を設定します。

ログの内容の解釈は InterSystems の担当者に任せるのが最善ですが、この内容には VisM で起こったことの大半のトレースと、サーバとの間で送受信されたメッセージすべてのフル・ダンプが含まれています。情報が少なすぎる場合よりも、多すぎる場合のほうが失敗する傾向にあります。必要な場合、実際に何が起きたのかをリアルタイムに記録したものとして、ログは非常に役に立ちます。

目的は Server プロパティと同じで、このプロパティに設定できる値のいずれかに設定できます。このプロパティは下位互換性のためにのみ提供されているので、新しいアプリケーションでは使用しないでください。詳細は、付録 "以前のバージョンをお使いの方へのご注意" を参照してください。

ユーザにキャンセルするかどうかを確認するときに表示されるメッセージを表す文字列で、4 つの部分に分割されています (PromptInterval プロパティを参照)。このプロパティは次の形式を持つ文字列です。

"prompt_message|title_text|OK_button_text|Cancel_button_text"

表示されるメッセージ・ダイアログ・ボックスにはウィンドウ・タイトル (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 プロパティが空ではなく、現在のネームスペースとは異なる場合、ネームスペースは指定どおりに変更されます。これはコードの実行前に行われます。

ネームスペースを変更するには多大なコストがかかることを覚えておいてください。詳細は、"最善の使用方法" を参照してください。

PLIST プロパティで使用される区切り文字列。詳細は、ミラーリングされた VisM プロパティ のセクションを参照してください。これは実行時に読み取り/書き込みが行われます。つまり、設計時には設定できません。これまでの経緯から、既定値は $C(13,10) という文字列となります。空の文字列が設定されている場合、事実上、区切り文字はなく、PLIST は単一の要素と解釈されます。ただし、このプロパティはサーバに送信されません。

待機時間を秒単位 (ミリ秒ではありません) で指定します。この時間の経過後、さらに待機するか、操作 (通常は、時間のかかるクエリ) をキャンセルするかをユーザに尋ねるプロンプトが表示されます。このプロンプトが表示されるのは、サーバがまだ応答していない場合のみです。このプロンプトは、さらに応答を待つか、操作をキャンセルするかを選択するためのオプションをユーザに提供します。MsgText プロパティは、この場合に表示されるメッセージの内容を表します。このプロパティが 0 または負の値の場合、プロンプトは表示されません。既定値は 0 です。

このプロパティの用途は 2 つあります。

• 特定のサーバに接続する場合、または現在接続されているサーバから切断する場合には、このプロパティを設定します。

• 実行時に、このプロパティを取得して、クライアントの接続先サーバを確認することができます。この場合、プロパティの値は多少異なる形式を持ちます。

このプロパティに接続文字列、接続タグ、二重引用符で囲まれた疑問符、または空の文字列を設定できます。接続文字列の詳細は、この章前半の "VisM 接続文字列" のセクションを参照してください。

Server プロパティを設定することは、SetServer() メソッドの呼び出しと同じ効果があります。詳細は、この章後半の "接続メソッドの比較" のセクションを参照してください。

Caché Direct では使用されません。このプロパティは、Microsoft Visual Basic 規約との互換性のために用意されています。これは任意の方法で使用できます。

クライアントがサーバからの応答を待機する時間 (ミリ秒) を表す整数値。これは、TCP 経由でメッセージが送信された直後から、Windows からデータの受信が報告されるまでの時間です。タイマが作動すると、つまり、許容時間内に応答が受信されなかった場合、接続は切断されます。これにより、通常はサーバで TCP エラーが発生し、サーバがシャットダウンされます。クライアントは、処理可能なエラー状態で、制御を取り戻します。アプリケーションが処理の続行を求める場合は、新しい CDConnect を作成する必要があります。これにより、新たにスレーブ・サーバ・ジョブが作成されます。このジョブはグローバルにはアクセスできますが、古いサーバ・ジョブのローカル状態には一切アクセスできません。

このプロパティが負の数または 0 である場合、クライアントは永久にメッセージが返されるのを待ちます。既定値は 60000 (60 秒) です。