@DbLookup (ODBC データソース) (式言語)

ODBC.INI ファイルのデータソース情報を使用して、適切な ODBC ドライバを起動します。起動されたドライバは、指定された DBMS、テーブル、列を特定し、キー列の値が指定されたキーと一致するレコードに属する列の値だけを返します。返される値リストのソートや、重複する値の削除、および Null 値の扱いもオプションで指定できます。

注: @DbLookup はデータを取り出すだけで、データの追加、削除、変更はできません。

構文

@DbLookup( "ODBC" : cache ; " data_source " ; " user_ID1 " : " user_ID2 " ; " password1 " : " password2 " ; " table " ; " column " : " null_handling " ; " key_column " ; " key " ; "Distinct" : " sort " )

パラメータ

"ODBC"

文字列引数。ODBC データソースにアクセスすることを示します。

cache

文字列引数。オプション。初回の検索では、"" または "NoCache" を指定します。 "" を指定した場合、次回の検索でも同じデータソースを検索する場合は、"ReCache" を指定できます。

"data_source"

文字列。アクセス対象の外部データソースの名前を指定します。この名前は、Data Source Administrator または odbc.ini ファイルで dsn (データソース名) として指定されています。データソースは、1 つ以上のデータベーステーブルの場所を表します。「データソースを指定する」を参照してください。

"user_ID1" : "user_ID2"

文字列リスト。外部データベースに接続するために必要なユーザー ID を指定します。アクセスする DBMS によっては 2 つの ID が必要な場合があります。「ID とパスワードを指定する」を参照してください。

"password1" : "password2"

文字列リスト。ユーザー ID に必要なパスワードを指定します。「ID とパスワードを指定する」を参照してください。

"table"

文字列。アクセス対象のデータベーステーブルの名前を指定します。

"column"

文字列。取り出すデータが含まれている列の名前を指定します。

"null_handling"

文字列。データを取り出すときの Null 値の扱い方を指定します。「Null の扱い方を指定する」を参照してください。

"key_column"

文字列。キー照合に使用する列の名前を指定します。

"key"

文字列、数値、日時、リスト。key_column で検索される値を指定します。データソースのキー列の型と一致する Notes の型を使用してください。

"Distinct"

文字列引数。オプション。重複する値をリストから削除してからデータが返されます。「Distinct を指定する」を参照してください。

"sort"

文字列引数。値のリストは昇順または降順にソートしてから返されます。「sort を指定する」を参照してください。

戻り値

valuesFound

文字列、数値、日時、これらのデータ型のリスト。指定した column の値が返されます。後述の「戻り値にアクセスする」を参照してください。

注: キーワードフィールドでの選択方法としてラジオボタンやチェックボックスを使用する場合、キーワードリストは文書が作成されたときまたは編集用に開かれたときだけ更新されます。標準の選択方法では、文書が再計算されるたびにキーワードリストも更新されます。

データソースを指定する

データソース名は、最大 32 文字の英数字で指定します。

ID とパスワードを指定する

これらの引数は、DBMS で必要な場合にのみ指定します。

ID を @DbLookup 式に保存する代わりに、Null 文字列 ("") を使用できます。ID が必要なときは、ユーザーに ID の入力を要求するプロンプトが表示されます。これは、自分の ID を他の設計者に見られたくない場合や、外部データにアクセスするときにユーザーに自分の ID を入力させたい場合に便利です。ただし、自動的に実行される式 (エージェントなど) には、必ず ID とパスワードを指定します。このような式は、情報の入力を要求しないからです。

データベースが開いたままのときは、データソースにアクセスするためのユーザー ID とパスワードの入力は、Domino のデータベースセッションごとに一度だけ必要です。ユーザーが Domino の別のデータベースを開いて同じデータソースにアクセスする式を実行する場合は、ユーザー ID とパスワードをもう一度入力する必要があります。

パスワードパラメータは、ID パラメータを指定した場合に限り必要となります。ID と同様に、パスワードを @DbLookup 式に保存することも、代わりに Null 文字列を使用して ODBC ドライバからプロンプトを出させることもできます。データベースパスワードが Null の場合は、式から省略できます。

例えば、ID とパスワードを完全に指定する場合は、次のように入力します。

テーブル名を指定する

テーブルの所有者名は省略可能ですが、テーブル名を明確にするために指定することもできます (DBMS が対応している場合)。所有者名とテーブル名はピリオドで区切り、"owner_name.table_name" という形式で指定します。

以下に例を示します。

"dbo.author"

Table で、アクセス対象の DBMS のデータベースのビューも参照できます。

Null の扱い方を指定する

Null 値の処理を制御するには、次のオプションを 1 つ指定し、コロンを付けて column パラメータに追加します。

key_column と key を指定する

"key_column" では、指定した "key" で検索する列を指定します。列名は、引用符で囲みます。DBMS 製品で列名の大文字と小文字が区別される場合は、大文字と小文字の区別も正確に指定してください。@DbLookup でデータを取り出すとき、キー列の値はソートされていなくても 構いません。

データソースのキー列と一致する Notes の型を使用して値を指定します。例えば、キー列が、整数、実数、浮動小数点数、倍精度実数といった数値型の場合、数値または数値となる式を指定します。キーの値が文字列の場合は、引用符で囲みます。日時の値は、Domino の形式ではなくデータベースの形式で入力する必要があります。例えば、DB2/2 の場合は 1996-01-31-12:00:00 ではなく 1996-01-31-12.00.00 を使用します。

キー列とキーの値を組み合わせたものが、選択ステートメントの「where」節を構成します。

"SELECT column WHERE key_column = key"

ODBC アプリケーションのインターフェースによって常にキー列の値とキーが等しいかどうかが調べられ、完全に一致するレコードのデータだけが返されます。キー列の値が指定した複数の値のいずれかと一致するかどうかを調べるには、キー値をリストとして指定し、アイテム間を "Red":"Blue":"Green" のようにコロン (:) で区切ります。この場合、OR 演算と同様に処理され、キー列の値が "Red" OR "Blue" OR "Green" と一致するすべてのレコードのデータが返されます。AND 演算を実行する場合や、キー列の値とキーが一致しないことを調べる場合は、@DbCommand を使用して正しいコマンド文字列を DBMS に渡します。また、キーの値が日時の場合に正しいコマンド文字列を渡すには、@DbCommand を使用します。これは、@DbLookup では日時の値が DBMS のコマンド言語の日時形式に正しく変換されるとは限らないためです。

型やその他の問題が原因で @DbLookup から正しい値が返されない場合は、@DbCommand で SELECT ステートメントを使用してみてください。

Distinct を指定する

Distinct 文字列引数は Domino の @Unique に似ています。ただし、Distinct ではデータが Domino に返される前 に重複する値が必ず削除されます。@Unique ではなく Distinct を使用すると、次の 2 つの利点があります。

注: 一部の ODBC ドライバは Distinct をサポートしていません。データに Null 値がある場合に Distinct を指定すると、通常は Null が 1 つ返されます。

sort を指定する

Distinct 文字列引数を使用するとき、コロンを付けて sort パラメータを付加することができます。sort パラメータには次のキーワードのいずれかを使用し、戻り値のソート方法を指定します。

ソート文字列引数を指定しないと、値はソートされずに返されます。

注: 一部の ODBC ドライバは sort キーワードをサポートしていません。式で Ascending と Descending の両方を指定すると、「引数が無効です」というメッセージが表示されます。

戻り値にアクセスする

複数の値が返されるときは、現在のフィールドに指定されている複数値の分離記号で区切られたリストの形式で返されます。

@DbLookup は、64KB を超えるデータを返すことはできません。次の公式を使用して、@DbLookup で返されるデータ量を調べます。

ユーザーの NOTES.INI ファイルに次のステートメントが含まれている場合は、

NoExternalApps=1

@DbLookup 式は無効になります。この場合、式が失敗するだけでエラーメッセージは表示されません。これは、@DbLookup を ODBC とともに使用した場合に限り起こります。

使用法

@DbLookup は、主にキーワード式で使用します。キーワードのリストをハードコーディングしてリストを定期的に更新する代わりに、@DbLookup を使用すると、外部データベーステーブルから動的に値のリストを取り出すことができます。

@DbLookup は、貼り付けエージェントでは使用できますが、メールエージェントでは使用できません。あまりないケースですが、取り出し対象のデータを含むテーブルが保存されているリモートサーバーが Domino サーバーと同じコンピュータ上に存在する場合、この関数は Web アプリケーションでのみ機能します。

例

  1. 次の式では、会社の制服として入手できる色の完全なリストが [inventory] データベースから取り出されます。データは、次のように保存されています。

    アイテム

    サイズ

    色

    Shirt

    Small

    赤

    Skirt

    Small

    Green

    Sweater

    中

    赤

    Trousers

    中

    Yellow

    ソートされている最初の列 (列 1、Item) の内容が「Shirt」または「Trousers」であるすべてのレコードの Color 列 (列 3) の内容全体を取り出すには、次のように指定します。

    @DbLookup("ODBC"; "INVENTORY"; ""; ""; "UNIFORMS"; "Color"; "Item"; "Shirt" : "Trousers")

    指定したキーのいずれかが含まれているレコードが複数あるため、結果はリストで返されます。

    Red:Yellow

    結果リストの値は、データベースで検出されたとおりに表示されます。ソートされずに、重複する値もそのまま表示されます。

  2. 次の例では、Microsoft SQL Server に付属する「pubs」というサンプルデータベースを使用します。次の式では、ODBC ドライバを使用して PUBLISHERS というデータソースにアクセスし、ユーザー「dbo」が所有する「authors」というテーブルを特定します。 このテーブルの「state」列内の値を、値「CA」と「TN」と比較します。[state] フィールドの内容が「CA」または「TN」であるレコードごとに、[au_lname] フィールドに保存されている値が返されます。作成者名は昇順にソートされ、Null 値は破棄されます。
    @DbLookup("ODBC";"PUBLISHERS";"dbo";"vanilla";
"dbo.authors";"au_lname":"Discard";"state";
"CA":"TN";"Ascending")
親トピック: 式言語: @ 関数リファレンス
関連概念:
@関数を使用して LS:DO 経由で外部データベースにアクセスする
ECL セキュリティを伴う @関数
関連資料:
@DbLookup (Domino データソース) (式言語)
@DbCommand (ODBC データソース) (式言語)
@DbColumn (ODBC データソース) (式言語)