指定されたビュー (またはフォルダ) で、最初のソート列の値が、指定されたキー値と一致するすべての文書を取得します。選択された文書ごとに、ビューの指定された列の内容か、指定されたフィールドの内容を返します。
@DbLookup( class : cache ; server : database ; view ; key ; fieldName ; keywords ) or @DbLookup( class : cache ; server : database ; view ; key ; columnNumber ; keywords )
class
文字列。アクセスするデータベースの種類を指定します。Domino® のデータベースを指定するには、"" または "Notes" を使用します。
cache
文字列引数。オプション。初回の検索では、"" または "NoCache" を指定します。 "" を指定した場合、次回の検索でも同じデータソースを検索する場合は、"ReCache" を指定できます。
server : database
文字列リスト。サーバーのロケーションとデータベースのファイル名を指定します。「サーバーとデータベースを指定する」を参照してください。
view
文字列。検索するビューまたはフォルダの名前を指定します。必ず [ビューのプロパティ] インフォボックスに指定されているビュー名全体を指定します。別名は省略できます。ビューのサブメニュー表示がある場合は、その名前も含めて指定します。「ビューを指定する」を参照してください。
key
文字列、数値、日時、これらのデータ型のリスト。値を取り出すために実際に読み込まれる文書を特定します。文書のキーは、ビュー内でソートされた最初の列に表示される値です。この列を再度ソートできる場合、結果は現在のソート順序に左右されることに注意してください。「キーを指定する」を参照してください。
fieldName
文字列。正しい文書が識別されたときに、データを取り出すフィールドの名前を指定します。「フィールド名を指定する」を参照してください。
columnNumber
数値。列番号を指定すると、指定したキーと一致するビュー内のすべての文書が検索され、それらの文書の指定した列に表示されている 値がすべて返されます。この場合、データの表示に使用される式は関係ありません。「列番号を指定する」を参照してください。
keywords
キーワード。オプション。複数のキーワードを連結できます。
valuesFound
文字列、数値、日時、文字列リスト。指定した fieldName や column で見つかった値、または文書の UNID が返されます。「戻り値にアクセスする」を参照してください。
最初にソートされた列内のどの文書もキーと一致しない場合は、@DbLookup によってエラー [エントリが索引に見つかりません] が返されます。このエラーは、@IsError または @IfError でテストすることができます。
server : database パラメータを指定する方法はいくつかあります。
レプリカは次の順序で検索され、最初に検出されたレプリカが使用されます。
ワークスペースにレプリカが 1 つあるときは、そのレプリカが使用されます。
ワークスペースに複数のレプリカがあり、積み重ねられているときは、最も上にあるレプリカが使用されます。
ワークスペースに複数のレプリカがあり、積み重ねられていないときは、現在のサーバーと一致するアイコンが検索され、そのレプリカが使用されます。現在のサーバーと一致するアイコンがない場合は、ワークスペースに最初に追加されたアイコンが使用されます。
レプリカが特定されると、以降の検索で時間を節約するためにワークスペースに追加されます。
ビューのパラメータは、ビュー (またはフォルダ) の全体名または別名で指定できます。例えば、[Last Name] ビューに別名「|LName」があり、[表示] メニューで [By Author] のサブメニューとして表示される場合は、[ビューのプロパティ] インフォボックスで次のように表示されます。
By Author¥Last Name|LName
このビューを @DbLookup で参照するとき、次のように別名の LName だけを引用符で囲んで指定できます。
"LName"
ビュー名に別名がない場合、[By Author] 名とサブメニュー表示の [Last Name] を引用符で囲んで (別名なしで) 指定します。また、このビュー名は式で使用するものであるため、Domino が正しく解釈できるように「¥」の前にもう 1 つ「¥」を付ける必要があります。
"By Author¥¥Last Name"
テストできる値は、キーと一致する (等しい) ものだけです。その他の < (より小さい) などの別の演算子は指定できません。
一致させるキーとして定数を指定するだけでなく、編集可能なフィールドの値を使用することもできます。例えば、[contactName] と [lookupComments] の 2 つのフィールドから成る [ContactInfo] フォームを作成できます。ユーザーが [contactName] フィールドに担当者名を入力すると、その担当者に関連付けられたコメントのリストが [lookupComments] フィールドに表示されるようにするとします。まず、[contactName] フィールドを編集可能な文字列フィールド (またはダイアログリストフィールドなどの選択肢リストフィールド) として設定します。[lookupComments] フィールドの入力確認式として、例えば次のコードを記述します。
@DbLookup("":"NoCache";"Sales":"Customers.nsf";"ContactList";contactName;"Comments")
ユーザーが、例えば「Susie Queue」という顧客名を [ContactInfo] フォームの [contactName] フィールドで入力または選択し、[F9] キーを押して文書を更新すると、[lookupComments] フィールドの式によって以下のタスクが実行されます。
[contactName] フィールドをキーとして指定しているため、@DbLookup 式が実行されるときは [contactName] フィールドの現在値が検索条件として使用されます。
検索が機能するには、ソートされた列がビュー内に存在しなければなりません。存在しない場合は Null 値が返されます。ソートされていても分類されていない複数値フィールドの場合、正確な結果は返されません。この列を再度ソートできる場合、結果は現在のソート順序に左右されます。
キーのタイプは、ソート列のデータ型と一致しなければなりません。そうしないと、一致が検出されません。
取り出されるのは、検索キーと完全に一致する値だけです。大文字と小文字は区別されませんが、スペースや分離記号は正確に一致しなければなりません。[PARTIALMATCH] キーワードを指定した場合を除き、全体が一致しなければなりません。
数値キーまたは日付/時刻キーを使用する場合は、キー値と列の値が完全に一致しなければなりません。列の「スタイル」設定を使用すると、情報を非表示にできる点に留意してください。このため、例えば、列に日付と時刻が含まれているにもかかわらず、日付しか表示されない場合もあります。この列で検索を行うには、表示されている日付だけでなく、完全に一致する日付/時刻値を指定する必要があります。
キーが値のリストになっている場合は、一致する行エントリをすべて連結したリストが検索結果となります。例えば、キー "Sam" を検索すると 7 が返され、"George" を検索すると 19 :4 が返される場合、キー "Sam":"George" を検索すると 7:19:4 が返されます。
キーのリストを使用した際、最初のキーがビューエントリと一致しない場合は、他のキーが一致しても検索は失敗します。ただし、最初のキーで一致が検出された場合は、後続の一致しないキーは単に無視され、エラーは発生しません。
検索で fieldName を指定すると、フィールドに実際に保存されている値が返されます。これはビューに表示される値とは異なる場合があります。指定したビューに表示されているどの文書のどのフィールドからもデータを取り出すことができますが、フィールドがビューの列として表示されていない場合は、そのフィールドを見つけるために文書全体が検索されるため、検索に時間がかかることがあります。@DbLookup を使用してリッチテキストフィールドからデータを取り出すことはできません。
一致した文書の中には、別のフォームを使用して作成したものであるために、指定したフィールドが含まれていない文書もあります。
ビューの列に基づく検索のほうが、ビューに表示されないフィールドに基づく検索よりも効率的です。最良の結果を得るには、値を取り出すフィールドがビューに表示されているようにしてください。
例えば、ビューが製品 ID で分類されており、検索キーに「01776」を、列に 2 を指定した場合、製品 ID 01776 のすべての文書の列 2 に表示される値が返されます。
columnNumber パラメータを指定するときは、ビューの列は左から右に数え、左端の列が列番号 1 となります。ただし、検索ではすべての列が数えられるわけではありません。これは、Domino がビューに索引を付ける方法の特性によるものです。
検索用の列番号は次の方法で計算します。
列の数え漏れがないことを確認します。例えば、ビューをソートしたり分類するために使用される列は表示されないことがあります。すべての列を確認するには、ビューを設計モードで表示します。
ここで求めた列番号を検索式で指定します。
@DbLookup により複数の値が返されるときは、現在のフィールドのインフォボックスに指定されている複数値の分離記号で区切られたリストの形式で返されます。
@DbLookup は、64KB を超えるデータを返すことはできません。次の公式を使用して、@DbLookup で返されるデータ量を調べます。
文字列を返す検索の場合
2 + (2 * 返されるエントリ数) + 全エントリの合計文字列サイズ
数値または日付を返す検索の場合
(10 * 返されるエントリ数) + 6
この関数は、列式、選択式、メールエージェントでは使用できません。
@DbLookup が含まれているデータベースを参照元 データベース、アクセスされるデータベースを参照先 データベースと考えます。
@DbLookup をエージェントで使用するとき、参照元データベースを管理するサーバーと同じサーバーまたは別のサーバーで実行されている参照先データベースのデータにアクセスできます。エージェントの署名者には、参照先データベースに対する [読者] 以上のアクセス権が必要です。
その他の種類の式やエージェントで @DbLookup を使用する場合は、ユーザーのクライアントに保存されているすべての参照先データベースに対して無制限にアクセスできます。参照先データベースが別のサーバーに保存されている場合、@DbLookup からそのサーバーにアクセスできるかどうかは、ユーザーの Notes ID に基づくエージェントの署名者のアクセスレベルによって決まります。
@DbLookup は、ビューの読み込みアクセスリストの影響を受けます。
従業員が事務用品の購入要求を記入する購買アプリケーションがあるとします。Notes アプリケーションによって、この情報を検索して自動的に文書に挿入するようにできます。
Mary Tsen は注文書を作成します。注文書番号、日付、要求者の各フィールドは、Notes により自動的に入力されます。Mary は注文書に数量、部品番号などの詳細を入力します。
Mary が注文書を保存するとき、文書の配送情報は、Domino ディレクトリからユーザーに関する情報を取り出す一連の @DbLookup 式を使用して計算されます。
この計算を行うには、計算結果フィールドを使用して、取り出す各フィールド (勤務地と電話番号) についての検索式を記述します。例えば、[Location] フィールドを取得する式は次のようになります。
@DbLookup("";"Purchasing":"Names.NSF";"People"; @Right(RequestedBy; "");"Location")この式は、Purchasing サーバー上の Domino ディレクトリ (Names.NSF) を開いて [ユーザー] ビューを検索し、注文書の [RequestedBy] フィールドの姓に一致する姓を持つ人物を検索するよう Domino に指示するものです。正しい文書が特定されると、ユーザー文書の [Location] フィールドから注文書の [Location] フィールドに情報がコピーされます。
同様の式により、Mary の電話番号が、ユーザー文書の [OfficePhoneNumber] フィールドから注文書の [Phone] フィールドにコピーされます。
「Purchasing」をキーに指定して @DbLookup を使用し、[OfficePhoneNumber] フィールドを取得します。この場合、ユーザー文書の [Department] フィールドに「Purchasing」が入力されている全従業員の電話番号が返されます。電話番号は、そのフィールドに対して選択されている複数値の分離記号を使用して、文字列のリストとして返されます。
@DbLookup("":"NoCache";"RESEARCH":"SMITH¥¥PROJECTS.NSF"; "In Progress";"Virus Check";"Status")