Notes C API探訪: ITEM_TABLE(データ型)

Notes/Dominoの文書には、フィールドデータが格納されています。Notes C APIではフィールドのことを「Item(アイテム)」という単語で表しています。

ビューの列に表示される値

Notesで文書を保存すると、ビューでその内容が表示されます。列式でデータが加工されているのを除き、フィールドデータを直接表示する設定になっていれば、そのデータが列に表示されます。至極当たり前のことですね。でもその当たり前が、実はとある設定に基づいていて、その設定条件に見合わないフィールドデータは、表示することができないことを知っている人は、意外と少ないかもしれません。

サマリー属性

もし、LotusScriptでNotesItemクラスを使ったことがある方なら、「IsSummary」というプロパティを目にしたことがあるかもしれません。「このアイテム(フィールドデータ)はサマリーかどうか」というサマリー属性を表すもので、読み書き可能なブール値です。
さて、「サマリー」とは一体何で、サマリー属性を持つとどんなことができるのでしょう？
サマリーを直訳すれば、「概要、要約」となります。実は、ビュー上に表示されるフィールドデータは、この「サマリー属性」を持ったフィールドに限られています。
また、これらサマリー属性の付いたアイテムの情報を集め、「要約された」データの集合を「サマリーバッファ」と呼びます。文書を検索するNSFSearch関数や、ビューの行情報を取得するNIFReadEntries関数などで大量の文書を捌く際、文書をオープンせず高速に内容を読み込む手段として用いられます。
ただし、サマリーバッファを通じて内容を更新することはできません。

以上のような特性を持つサマリーですが、Notesクライアントでは、リッチテキストフィールド以外のフィールドデータには、自動的にサマリー属性が付与されます。LotusScriptでは、NotesItemクラスを介して、アイテムにサマリーを付けるかどうか細かく制御できるようになります。

Notes C APIでのサマリーバッファ

Notes C APIでは、ビュー/フォルダはもちろん、文書を検索する場合などでもサマリーバッファが活躍します。多くの文書を捌く際、文書オープンのような、少しでもコストのかかる作業を減らしたい時、サマリー化したデータで事足りるのであれば、サマリーバッファを便利に使いましょう。

サマリーバッファはITEM_TABLE構造体を先頭とする可変長のデータ構造になっています。さらに、サマリーバッファには名前付きと名前なしの2種類があります。

名前付きサマリーバッファ

最初に名前付きサマリーバッファの構造を見ていきましょう。

小さくて見づらいかもしれませんが、なんとか工夫して大きくしてみてみてください(汗)。
先頭のITEM_TABLE構造体は、LengthとItemsの2つのUSHORT型を持っています。Lengthはサマリーバッファ全体のサイズを、Itemsはアイテムの数を表します。
続くのはアイテム数分のITEM構造体で、これらはNameLengthとValueLengthの2つのUSHORT型を持っています。NameLengthはそのアイテムの名前、ValueLengthはそのアイテムの値、それぞれの長さを表します。
最後のITEM構造体の後に、各アイテムの名前(フィールド名)と値を1セットとした構造がアイテム数分続きます。値には、先頭2バイトにデータタイププレフィックス(TYPE_***)が付くので、このタイプ値を元に値をパースをすることができます。
この図表の場合、0番目にSubjectフィールドのLMBCS文字列「タイトル」、1番目にTimeフィールドのTIMEDATE型、2番目にNumberフィールドのNUMBER型のデータ3つを持った、全体で67バイトのサマリーバッファということになります。

名前なしサマリーバッファ

続いて名前なしサマリーバッファを見ていきます。さきほどの名前付きサマリーバッファ例を名前なしにした場合の図表を以下に示します。

同じように、先頭にはITEM_TABLE構造体があり、続いてアイテム数分の値の長さ(USHORT型)があり、その後にデータタイププレフィックス付きの値が順に続きます。
ご覧のとおり、名前に関する情報が省かれています。そして、名前ありかなしかという情報はITEM_TABLE構造体には含まれていないので、これだけでは区別できません。名前なしサマリーバッファについては、後日どこかでお話ししたいと思います。

まとめ

サマリーバッファとITEM_TABLE構造体について説明してきました。次回以降でこれらを使ったコード例をご紹介していきます。