LC LSX を使用して作業する

Lotus® Connector の代表的な用途は、外部システムに存在するデータの収集、作成、変更などです。例えば、Notes® アプリケーションのフォームには多数のデータフィールドがあります。ユーザーが入力を完了してボタンをクリックすると、フォームのデータを取り出して Oracle へのコネクションを確立するスクリプトがアクティブ化されます。これによってテーブルから該当する情報が検索され、Notes のフォームが更新されます。このスクリプトは、以下のタスクを実行します。

アクティブな Notes フォームにアクセスする
入力されたデータを収集する
外部システムへのコネクションを作成する
入力された値を基にデータを選択する
外部システムからデータをロードする
アクティブな Notes フォームに結果を格納する

このタスクを実行する簡単なスクリプトを以下に示します。Notes フォームには、「Customer」という名前のテキスト入力フィールドが 1 つだけあるものとします。スクリプトでは、[Customer] フィールドの値を使用して、DB2® 内で該当する顧客情報を検索します。次に、該当する顧客の住所と電話番号を返し、[Address]、[City]、[State]、および [Phone] というフィールドを使用してフォームに戻り値を格納します。

注: コードスタイルの指定は特にありません。オブジェクトをスクリプトの先頭でまとめて宣言するか、コードの近くで宣言するかは好みの問題で、スクリプトの実行には関係ありません。この例では、説明しやすいように宣言とコードを 1 つにまとめてあります。

スクリプトを作成するときの最初のステップは、LotusScript® Extensions for Lotus Connectors のロードです。これには、Uselsx ステートメントを使用します。変数をチェックするオプションや、文字列の比較を単純化するオプションを使用することもできます。

Option Public
Option Explicit

Uselsx "*lsxlc"

注: LEI を使用する場合は、Dim LCSession を名前付きセッションとして使用します (これはデフォルトのログ文書名となります)。また、LCConnection は LEI Administrator で作成された既存の名前付きコネクション文書として宣言する必要があります。詳しい説明と例については、各メソッドの章の概要部分を参照してください。

スクリプトの残りの部分は、フォームのボタンの Click イベントに配置します。エラーはユーザーに表示されます。この例の末尾に、簡単なエラーハンドラがあります。LSX Session クラスの Status プロパティを使用すると、エラーハンドラが LSX のエラーと LotusScript のエラーのどちらで起動されたかを判断できます。LSX によってエラーが報告されるすべてのケースで、LotusScript の Error$ にエラー情報が格納されます。ただし LSX オブジェクトを作成した直後は、LSX のこの他のエラー情報を LotusScript のエラーステートメントで取り出すことはできません。セッションのステータスを作成および初期化すると、このような情報がエラーハンドラで使用できるようになります。

通常のエラー処理では、セッションオブジェクトを作成する必要はありません。

Sub Click (Source as Button)
    On Error Goto Handler
    Dim session As New LCSession
    session.ClearStatus

入力値は、現在アクティブな文書にあります。この情報には NotesUIDocument からアクセスできます。NotesUIDocument は、NotesUIWorkspace の CurrentDocument プロパティを通して取得できます。

    Dim wksp As New NotesUIWorkspace
    Dim uidoc As NotesUIDocument
    Set uidoc = wksp.CurrentDocument

次に、Lotus Connector for DB2 へのコネクションを確立します。コネクションを作成した後は、そのプロパティにアクセスしてターゲットシステムへのコネクションをカスタマイズできます。代表的なプロパティには、Database または Server (またはその両方)、UserID、および Password があります。プロパティでは大文字と小文字は区別されません。

各 Lotus Connector のプロパティ一覧については、付録 B を参照してください。

次のコードでは、Rainbow という名前の DB2 システムに jdoe として接続します。パスワードは gold です。

    Dim src As New LCConnection ("db2")
    src.Database = "Rainbow"
    src.UserID = "jdoe"
    src.Password = "gold"
    src.Connect

コネクション経由の照会では、Catalog、Execute、Select および Call の 4 つのコネクションメソッドを使用できます。

Catalog オペレーションは、外部システム内のメタデータ情報を取得するときに使用します。例えば DB2 データベースのテーブルや、Sybase の特定のテーブルの列などが該当します。Catalog のオプション一覧については、Catalog メソッドの説明を参照してください。
Execute、Select および Call の各メソッドは、コネクションからのデータの結果セットを作成します。これらのメソッドは、インターフェースが大きく異なります。
Execute ステートメントは、Connector 固有のコマンドステートメントを使用して結果セットの内容を決定します。このインターフェースは、外部システムのコマンド構造を熟知していて、Connector 間でスクリプトを移植する必要がない場合に便利です。
Select メソッドは、キー名、値、および条件フラグの組み合わせによって、目的の結果セットの内容を指定します。このインターフェースはすべての Connector に有効で、Connector のコマンド言語についての知識は必要ありません。
Call メソッドは Select と似ていますが、バックエンドのプロシージャまたは関数を呼び出すときに使用します。キーの代わりにパラメータを使用します。

例では、必要なデータは「Customer」という DB2 のテーブルに格納されているので、コネクションの Metadata プロパティで指定しています。必要なレコードは、Notes フォームの入力値によって指定された名前の顧客のレコードだけです。

顧客を選択するには、キーリストを作成します。デフォルトのキーフラグである LCFIELDF_KEY は、完全一致することを指定します。「より大きい」や「類似」などの完全以外の一致が必要な場合は、フィールドのフラグプロパティと該当する定数との論理和がとられます。どの場合も、キーフィールドにはオプションの条件フラグ定数の他に LCFIELDF_KEY 定数が必要です。

    Dim keys As New LCFieldList
    Dim field As LCField

    src.Metadata = "Customer"
    Set field = keys.Append ("Name", LCTYPE_TEXT)
    field.Flags = LCFIELDF_KEY
    field.Text = uidoc.FieldGetText ("Customer")

コネクションの Select メソッドは、外部システムからのキーリストに一致するすべてのレコードの結果セットを作成します。キーリストの代わりに LotusScript のキーワード「Nothing」を使用すると、指定したメタデータのすべてのレコードが選択されます。この例では、DB2 テーブル「Customer」のすべてのレコードが選択されます。この例で必要となるのは、Notes フォームの入力値と一致する顧客レコードのみです。このように制限するために、キーリストを作成します。

結果セットを受け取るフィールドリストは、この時点では空です。選択によって、DB2 テーブルのフィールドがフィールドリストに取り込まれます。メタデータのフィールドに必要でないものがある場合、必要なフィールドだけで構成されるように結果セットを制限できます。その場合は、選択の前にフィールドリストを作成するか、コネクションの FieldNames プロパティを設定します。

    src.FieldlNames = "Address, City, State, OfficePhone"

選択の結果として、選択されたレコード数が返されます。一致するレコードがない場合はゼロ (0) が返され、レコードが見つかっても総数が不明の場合は LCCOUNT_UNKNOWN が返されます。データが見つからなかった場合は必ずゼロが返されるため、このことを調べてエラー処理や分岐を行います。

    Dim fields As New LCFieldList
    If (src.Select (keys, 1, fields) = 0) Then End

結果セットが作成され、一致するレコードが 1 つあります。結果セットのデータはまだ取り出されていません。コネクションの Fetch メソッドで、外部システムからフィールドリストにデータを読み込みます。フィールドリストの個々のデータ値には、拡張クラスプロパティを使用してアクセスします。フィールドリスト内の各フィールドには、対応する名前のプロパティがあります。このプロパティは値の配列で、LSX LC のデータ型に最も近い LotusScript のデータ型が使用されます。

    If (src.Fetch (fields) > 0) Then
        Call uidoc.FieldSetText ("Address", fields.Address(0))
        Call uidoc.FieldSetText ("City", fields.City(0))
        Call uidoc.FieldSetText ("State", fields.State(0))
        Call uidoc.FieldSetText ("Phone", fields.OfficePhone(0))
    End If

注: 複数のレコードを操作するスクリプトを作成するときは、ループの外側でフィールドリスト内のフィールドを特定し、そのフィールドを使用してデータにアクセスするほうが効率的です。詳しくは、この章の「パフォーマンス」を参照してください。

これで、外部システムからデータが取得され、Notes フォームに挿入されました。この例の処理は以上です。最後に、Notes 文書を更新してユーザーに新しいデータを表示します。

    uidoc.Refresh
    [End]

この例の最初の行で、エラーハンドラが指定されています。LSX エラーの有無をテストするとき、オブジェクト作成エラーが発生した場合は最初に追加情報が取得されます。セッションオブジェクトが存在しない状態で、エラーハンドラでの以降のテストも行わない場合は、DB2 へのコネクション作成時の障害により「製品のオブジェクトの作成中のエラーです。」という LotusScript のメッセージが生成されます。同じエラー状態でも、LSX からは「Error: Cannot load LSX library 'db2'」が報告されます。

Handler:
    If (Session.Status <> LCSUCCESS) Then
        Messagebox Session.GetStatusText, 0, "The following Lotus Connector error has occurred"
    Else
        Messagebox Error$, 0, "The following LotusScript error has occurred"
    End If
    End
End Sub

この例は非常に単純です。これは、Lotus Connector、クラス、およびコネクション、メタデータ結果セット、フィールドリスト、フィールドおよびデータ間の関係を説明するためのものだからです。