VisM コントロールの使用に関する基本

接続文字列と接続タグ

Caché に接続するための構文を記述する前に、その構文で使用される接続文字列と接続タグについて知っておくと役立ちます。

基本的な接続文字列

接続文字列は、次の形式を持つ文字列です。

"CN_IPTCP:server[port]"

この引数の最初にある CN_IPTCP は接続メソッドで、必ず TCP です。2 つ目は Caché スーパーサーバが稼動しているサーバの名前、または IP アドレスとポートです。例えば、VisM1 という VisM の接続を設定するには、次の構文を使用します。

VisM1.Server="CN_IPTCP:127.0.0.1[57772]"

この基本文字列を拡張することもできます (詳細は、"VisM.ocx コントロールの詳細" の章にある "VisM 拡張接続文字列の構文" で説明しています)。この拡張機能は、一般には使用されません。

間接参照を使用した接続

代わりに、ローカルに定義されたデータベースのエイリアスに対する間接参照を使用することもできます。この場合、"@servername" という形式の文字列を使用します。ここでは、servername は Caché Server Manager 内で指定されたものです (Caché サーバ・マネージャの使用法の詳細は、"Caché システム管理ガイド" の "リモート・サーバ接続の定義" を参照してください)。これらのエイリアスは、クライアント・マシンに対してローカルなものです。クライアント・マシンが、対応する Caché サーバのエイリアスに対する名前付け規約に従っている場合のみ、この方法でハード・コーディングすることができます。

例えば、サーバ名 unix1 への VisM オブジェクト VisM1 の接続を設定するには、次の構文を使用します。

VisM1.Server="@unix1"

Note:

Kerberos 認証を使用する接続を開くときには、間接参照を使用することをお勧めします。Caché サーバ・マネージャでは、認証方法としての Kerberos の設定、接続のセキュリティ・レベルの指定、およびサービス・プリンシパル名の定義を行えます。

ユーザ・プロンプト

接続文字列を使用できる任意の場所で、この文字列の代わりに二重引用符で囲まれた疑問符 ("?") を使用することができます。この場合、クライアント・マシンで定義されているサーバ・エイリアスを 1 つ選択するように求めるプロンプトが表示されます。

例えば、次の構文を使用すると、ユーザに対して VisM1 という VisM の接続を求めるプロンプトが表示されます。

VisM1.Server="?"

接続タグ

場合によっては、Caché への新しい接続を作成するときに、オプションの接続タグを提供できることがあります。これは、作成中の CDConnect とそのチャネルに対する名前となります。 特定のクライアント・プロセス内で、すべてのタグが一意であることを確認するのはユーザの責任です。

その後、VisM に接続したときに、接続文字列ではなく、既存の CDConnect の接続タグを指定することができます。明示的にチャネルを共有するには、この方法が主に使用されます。例えば、VisM1 という VisM の接続を設定するには、次の構文を使用します。

VisM1.Server="TagA"

また、VisM2 が接続され、タグが割り当てられている CDConnect に VisM1 を接続するとします。接続タグ自体を使用したくない場合は、次のように ConnTag プロパティを使用できます。

VisM1.Server=VisM2.ConnTag

Caché への接続

接続は VisM を CDConnect にアタッチする動作です (必要に応じて、CDConnect を作成します)。現在、VisM が CDConnect オブジェクトにアタッチされている場合、まず、これが CDConnect から切断されます。

まだ接続されていない場合

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")

CDConnect のチャネルの変更

既存の CDConnect のチャネルを変更するには、次の方法のいずれかを使用します。

• Server プロパティに、接続文字列と同じ値を設定します。

• 最初の引数として、接続文字列を使用して、SetServer() メソッドを呼び出します。

どちらの場合も、CDConnect により、現在接続中のサーバ・プロセスが停止、切断され、その後、新しいサーバ・プロセスが開始、接続されます。

Caché からの切断

Caché サーバから切断するには、次の方法のいずれかを使用します。

• Server プロパティに、空の文字列と同じ値を設定します。

• 引数として、空の文字列を使用して、SetServer() メソッドを呼び出します。

このような操作の結果、CDConnect が破棄されることはありません。また、サーバ・チャネルが存在する場合、これが影響を受けることもありません。次のセクションで説明するとおり、CDConnect は、アクセスが不可能になるまで (自動的に破棄されたとき)、または明示的に破棄されるまで存在します。

CDConnect の破棄

CDConnect とそのチャネルを破棄するには、DeleteConnection() メソッドを呼び出します。もちろん、このメソッドによりサーバ・プロセスも停止します。次に例を示します。

VisM1.DeleteConnection()

方法の概要

以下のテーブルは、Caché との接続および切断方法をまとめたものです。どんな場合でも、Server プロパティを設定することには、SetServer() メソッドの呼び出しと同じ効果があります。

重要 ： * このような操作の結果、CDConnect が破棄されることはありません。また、サーバ・チャネルが存在する場合、これが影響を受けることもありません。CDConnect は、アクセスが不可能になるまで (自動的に破棄されたとき)、または明示的に破棄されるまで存在します。

次の図は、Connect() メソッドと SetServer() メソッドの違いをまとめたものです。

ミラーリングされた基本的な値の使用

ミラーリングされた基本的な VisM プロパティは、文字列プロパティ P0、P1、P2、P3、P4、P5、P6、P7、P8、P9、および VALUE　です。 サーバがクライアント・コマンドを実行しているときに、サーバ・プロセスは、VisM のプロパティと同じ値を持つ、同じ名前のローカル値を持っています。サーバでの変更に続いて、クライアントがサーバから応答メッセージを受信したときに、クライアントでプロパティが変更されます。

VALUE プロパティにはもう 1 つ機能が用意されています。"コードの実行" に説明されているとおり、Code プロパティの値が式である (つまり、先頭にドル記号または等号が付いている) 場合、サーバは、VALUE プロパティに指定されている式の結果を返します。

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"
  

  

  クライアントに戻ったときの、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 がクリアされる (その後、サーバにリスト要素の個数を数えさせる) ことを意味しています。

Visual Basic コールバックをサポートするための要件

特定のフォームでコールバックを使用できるようにするための要件は次の 2 つです。

• このフォームには VisM コントロールが含まれていなければなりません。

• そのフォーム上のコントロールへの最初のサーバ参照をする前に、(通常は、Form_Load イベント・コールで) 次のような呼び出しを行います。

  CreateDispatch Me, VisM1
  

  

  ここで、Me は現在のフォームへの Visual Basic 参照で、VisM1 はそのフォーム上での VisM 名です。CreateDispatch 関数は <cache-install-dir>\dev\cdirect\VBRUN.BAS モジュールの一部です。プロジェクト内にこのモジュールが含まれていなければなりません。この関数は、フォーム上にコントロールのリストを作成し、将来の参照に備えて、これらのコントロールを VisM の非表示プロパティに格納します。

コントロールのプロパティの参照

コントロールのプロパティを参照するには、以下の特別な ObjectScript 構文を使用します。

_[formname!]controlname[(controlindex)].propertyname[(propertyindex)]

角かっこ内の要素は省略可能です。また、かっこ類は構文の一部ではありません。 先頭の下線は必須です。formname を省略した場合、このフォームは、VisM から現在のメッセージが送信されているフォームであると見なされます。controlname と propertyname は省略できません。コントロールがコレクションの 1 つである場合、controlindex を指定する必要があります。プロパティがコレクションである場合は、propertyindex は必須です。 例えば、現在のフォームにあるテキスト・コントロール txt1 のテキスト・プロパティを取得するには、次のコードを使用します。

Set x=_txt1.Text

テキスト・プロパティを設定するには、次のコードを使用します。

Set _txt1.Text="something"

ObjectScript では、下線も連結演算子なので、その意味が不明確な場合には、かっこを使用してください。

コントロールのメソッドの実行

コントロールのメソッドを実行するには、以下の構文を使用します。

Do _[formname!]controlname[(controlindex)].method[(args)]

例えば、リスト・ボックス list1 に項目を追加するには、次のコードを使用します。

Do _list1.AddItem("item data")

Unicode とロケールの問題

サーバに送信されるすべてのプロパティについて、その値に使用できるのはテキスト文字のみです。この制約は、Caché Direct により設定または取得される Visual Basic プロパティすべてに適用されます。詳細は、"クライアント・ユーザ・インタフェースへのコールバック" のセクションを参照してください (一部の環境での作業では、この制約に対する例外もありますが、この場合でも一般的な要件は存在します。)

Caché サーバは、8 ビット または 16 ビット (Unicode) モードのいずれかで動作します。クライアントとサーバの間の最初の通信では、サーバはクライアントにサーバのモードを知らせます。次に、以下の操作を行います。

• サーバが Unicode の場合、すべてのクライアントはすべての文字列を Unicode に変換してから、サーバに送信します。この結果、メッセージのサイズが大きくなる可能性がありますが、どのロケールで動作しているどのクライアントでも、サーバと確実に通信できるようになります。

• サーバが 8 ビット・モードの場合、クライアントによる文字列の変換は一切行われません。サーバと同じロケールを使用していないクライアントがある場合、サーバがデータベースに書き込みを行ったときにデータが失われるか、混乱する可能性が高くなります。これは、一部の文字では、ロケールが変わると意味も変わるためです。したがって、クライアントから受信したものを変換するか、翻訳するかはアプリケーションの責任になります。

メッセージのサイズ

これまでの経緯から、クライアントとサーバの間ではどちらの方向でも、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 文字を超えないように確認することをお勧めします。

簡単な例 ： Lightweight ターミナル

これは Visual Basic で 1 つのクライアント・フォームを作成する方法を示した小さなサンプル・アプリケーションです。ユーザはこれを使用して、ObjectScript を 1 行入力し、結果を得ることができます。このアプリケーションでは、可能な限り既定値が使用されています。また、エラー・チェックはほとんど行われません。

このサンプルでは、ローカル・マシンに Caché サーバが実行されていること、Caché Direct コンポーネントがインストールされていることを前提にしています。 使用しているマシンで Caché が実行されていることを確認してください。

Visual Basic を起動します。フォームを使用して、新しい Standard EXE プロジェクトを作成します。[プロジェクト] または [コンポーネント] メニューを使用して、ツールボックスに VisM コントロールを追加します。このフォームに、コマンド・ボタンを 1 つ (Command1)、テキスト・ボックスを 2 つ (Text1 および Text2)、VisM コントロールを 1 つ追加します。1 つ目のテキスト・ボックスは、簡単な 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

Form_Unload メソッドに、次の行を追加します。

VisM1.Server = ""

プロジェクトを実行します。 フォームが表示されたら、コマンド・ボタンをクリックします。[Choose Server Connection] ダイアログが表示されます。[LOCALTCP] を選択し、[OK] を押します。[Text1] フィールドは空のままにしておいて、[Command1] コマンド・ボタンをクリックします。[Text2] に構文エラー・メッセージが表示されます。これは、ObjectScript の行を入力しなかったためです。

[Text1] に「$H」と入力します。コマンド・ボタンをもう一度クリックします。現在日時が、$H 形式で [Text2] に表示されます。

アプリケーションを終了します。

その他の例

以下のサンプル・コードを考えてみましょう。

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 プロパティを更新して出力します。