Notes C API探訪: 式ハンドルの使用方法(その1)

コンパイルした＠式は、そのままでは実行(評価)することはできません。前回「テキスト」の式をコンパイルして、「式ハンドル」を得ることができました。この式ハンドルを実行するには、(1)ハンドルをロックする、(2)計算ハンドルを得る、と二段階の準備を経てから式を実行します。

式ハンドルをロックする

FORMULAHANDLE型の式ハンドルをロックするには、Notes C API探訪: メモリハンドルの回でお伝えしたOSLockObjectを使用します。ロックされたハンドルは実アドレスへのポインタを返します。

ロックしたハンドルから計算ハンドルを得る

ロックした式ハンドル(ポインタ)から計算ハンドルを得るには、NSFComputeStartを使用します。計算ハンドルはHCOMPUTE型になります。NSFComputeStart関数は、ロック済み式ハンドルから計算ハンドルを取得します。

#include <nsfsearc.h>
STATUS LNPUBLIC NSFComputeStart(
  WORD Flags,
  void far *pCompiledFormula,
  HCOMPUTE far *rethCompute);

Flagsは、必ず0を指定します。
pCompiledFormulaは、ロック済み式ハンドル(ポインタ)を指定します。
rethCompute、計算ハンドルを返す変数へのポインタを指定します。計算ハンドルは整数値ではなくポインタなので、初期化する時はnullptrを使用します。

計算ハンドルを実行する

計算ハンドルになった式を実行するにはNSFComputeEvaluate関数を使います。

#include <nsfsearc.h>
STATUS LNPUBLIC NSFComputeEvaluate(
  HCOMPUTE hCompute,
  NOTEHANDLE hNote,
  DHANDLE far *rethResult,
  WORD far *retResultLength,
  BOOL far *retNoteMatchesFormula,
  BOOL far *retNoteShouldBeDeleted,
  BOOL far *retNoteModified);

hComputeは、計算ハンドルを指定します。
hNoteは、式を文書に対して評価する場合、文書ハンドルを指定します。式単独で評価する場合は0を指定します。
rethResultは、評価した結果をデータプリフィックス(先頭に付くWORD型の値)付きのデータメモリへのハンドルを返す変数へのポインタを指定します。
retResultLengthは、データメモリのサイズを返す変数へのポインタを指定します。
retNoteMatchesFormulaは、選択式に文書がマッチしているかを返す変数へのポインタを指定します。
retNoteShouldBeDeletedは、式が文書の削除を示しているかを返す変数へのポインタを指定します。
retNoteModifiedは、文書が式により変更されたかを返す変数へのポインタを指定します。

計算ハンドルの使用を終了する

使用を終えた計算ハンドルは、NSFComputeStop関数で使用を終了します。

#include <nsfsearc.h>
STATUS LNPUBLIC NSFComputeStop(HCOMPUTE hCompute);

hComputeは、使用中の計算ハンドルを指定します。

式ハンドルの使用を終了する

式ハンドルがロックされたままであれば、OSUnlockObjectでアンロックします。再度ロックする必要がなければ、OSMemFreeで式ハンドルを解放します。

まとめ

＠式をC APIで使用する大まかな流れをまとめると次のようになります。

1. テキスト式→式ハンドル(NSFFormulaCompile)
2. 式ハンドル→ロック済みポインタ(OSLockObject)
3. ロック済みポインタ→計算ハンドル(OSComputeStart)
4. 計算ハンドル→実行(OSComputeEvaluate)
5. 計算ハンドル→停止(OSComputeStop)
6. ロック済みポインタ→アンロック(OSUnlockObject)
7. 式ハンドル→解放(OSMemFree)

次回は、サンプルコードを用いて＠式を使用する流れを説明します。