Notes C API探訪: RANGE(データ型)その1

RANGE型は、数値型(NUMBER型)、日時型(TIMEDATE型)で複数値を扱うための構造体ですが、LIST型とは違い、「範囲」という概念も持ち合わせています。

#include <global.h>
typedef struct {
 USHORT ListEntries;			/* list entries following */
 USHORT RangeEntries;		/* range entries following */
               /* now come the list entries */
               /* now come the range entries */
} RANGE;

ListEntriesは、数値、または日時の個数を示します。
RangeEntriesは、日時のペア値の個数を示します。

ここで2つの疑問が湧きます。
1つは「ペア値とはなにか」もう1つは「数値にペア値はないのか」です。

まず「ペア値」ですが、ペア値とは次のような構造体のことをいいます。

#include <global.h>

typedef struct {  /* a float range entry */
 NUMBER Lower;
 NUMBER Upper;
} NUMBER_PAIR;

typedef struct {  /* a timedate range entry */
 TIMEDATE Lower;
 TIMEDATE Upper;
} TIMEDATE_PAIR;

数値も日時も、Lower値とUpper値の2つの値で構成されています。これがペア値で、それぞれ数値の範囲、日時の範囲を表します。

次に「数値にペア値はないのか」ですが、ご覧のとおり、存在します。扱えないことはありません。NUMBER_PAIRを単独で使う分には問題ないでしょう。
Notes C APIのデータ型としては存在しますが、実はNotesクライアントから「数値の範囲」を入力する手立てがありません。また、Notes C APIのリファレンスには「Notes/Dominoでは数値の範囲はサポートされていないので、RANGE.RangeEntriesは0を指定しなくてはいけない」とあるので、基本的には使わないようにします。

日時のペア、TIMEDATE_PAIR型の方は問題なく使えます。ですが、この型のままではNotes文書のフィールドに書き込むことはできません。フィールドデータとしてTIMEDATE_PAIR型を保存する場合は、RANGE型に続く日時範囲エントリーとしてのみ保存できます。そのため、日時範囲のデータが1つでも複数でも、Notes文書に保存する時はRANGE型をヘッダーとしたメモリ配置で書き込みます。

以下は、日時におけるRANGE型のメモリ配置表です。

LISTと違い、個々のデータの長さは一定しているので、各エントリーのバイト数を保管する領域はありません。数値型の場合はsizeof(NUMBER)とsizeof(NUMBER_PAIR)のバイト数で計算すればよいことになります(事実上TIMEDATE型とNUMBER型はいずれも8バイトなので同一視できるでしょう)。
また、LIST型にはいくつかのサポート関数がありましたが、RANGE型にはそれらにあたる関数が見当たりません。ほとんど自前でメモリ操作をすることになります。可変長のエントリーを扱うLISTよりもメモリ操作は楽ですが、それでもバグの余地を残しそうで気を遣います。