InterSystems コールアウト・ライブラリの作成

ZFEntry テーブルの作成

すべてのコールアウト・ライブラリは、ZFEntry テーブルを定義する必要があり、これにより Caché がコールアウト関数をロードしてアクセスできるようになります (簡単な例は “コールアウト・ライブラリの概要” を参照してください)。ZFEntry テーブルは ZFBEGIN で始まり ZFEND で終わるマクロ・コードのブロックによって生成されます。これら 2 つのマクロ間で、関数を公開するごとに 1 回、ZFENTRY マクロを呼び出す必要があります。

各 ZFENTRY 呼び出しは、以下の 3 つの引数をとります。

   zfentry(zfname,linkage,entrypoint)

ここで、zfname は $ZF 呼び出し内で関数を指定するために使用される文字列、linkage は引数を渡す方法を指定する文字列、entrypoint は C 関数のエントリ・ポイント名です。

既定では、ZFEntry テーブルは、静的にリンクされている関数にのみ使用できるコードを生成します (詳細は、“静的にリンクされたコールアウト関数” を参照してください)。コールアウト・ライブラリを作成するには、マクロ・コードがライブラリ関数を見つけるための別のメカニズムを生成するようにするスイッチである #define ZF_DLL 指示文をコードに含める必要があります。静的ポインタ・テーブルの代わりに、内部 GetZFTable 関数が生成されます。コールアウト・ライブラリがロードされると、Caché はこの関数を呼び出して後続のライブラリ関数名の検索用にライブラリを初期化します。

Note:

ZFEntry のシーケンス番号

ZFEntry テーブル内のエントリの位置が重要となる場合があります。$ZF(-5) および $ZF(-6) インタフェース (次の章 “コールアウト・ライブラリ関数の呼び出し” で説明します) は、両方ともテーブル内でシーケンス番号 (1 で始まる) を指定することによってライブラリ関数を呼び出します。例えば、$ZF(-6) は以下の呼び出しを使用して ZFEntry テーブル内の 3 番目の関数を呼び出します。

   x = $ZF(-6,libID,3)

ここで libID はライブラリ識別子、3 はテーブル内の 3 番目のエントリのシーケンス番号です。

リンクの概要

各 ZFENTRY 文 (“ZFEntry テーブルの作成” を参照) では、引数が渡される方法を説明する文字列が必要です。例えば、"iP" は、整数と整数へのポインタの 2 つのパラメータを指定します。2 番目の文字は、2 番目の引数が入力と出力の両方に使用されることを指定するために大文字になっています。コードは、最大で 32 の実パラメータおよび仮パラメータを持つことができます。

大文字のリンク・タイプを指定する場合 (i を除くすべてのリンク・タイプで許可されている)、入力と出力の両方にこの引数を使用することができます。1 つの出力引数のみが指定されている場合は、その最終値は関数の返り値として使用されます。複数の出力引数が指定されている場合は、すべての出力引数がコンマ区切りの文字列として返されます。

出力引数は入力引数として使用する必要はありません。すべての入力引数の後に出力限定引数を指定する場合、関数は出力引数のいずれも指定することなく呼び出すことができます (例は、“コールアウト・ライブラリの概要” を参照してください)。

ObjectScript プログラマの観点からすると、パラメータは入力のみです。実パラメータの値は $ZF 呼び出しによって評価され、C ルーチン宣伝内の仮パラメータにリンクされます。C 仮パラメータへの変更は失われるか、または$ZF 返り値にコピー可能になるかのいずれかです。

ZFENTRY マクロが、仮パラメータを返り値として使用するように指定しない場合は、$ZF 呼び出しは空の文字列 ("") を返します。リンク宣言は、1 つ以上の出力パラメータを含むことができます。この場合、すべての返り値は単一のコンマ区切り文字列に変換されます。複数の返り値間に挿入されたコンマと、1 つの返り値内に存在するコンマとを区別する方法はないため、最後の返り値のみがコンマを含むようにします。

以下のテーブルは、利用可能なオプションを説明しています。

1. i、p、d、f — 数値引数が指定されると、Caché では文字列の入力引数が許可されます。詳細は、“数値リンクの使用” を参照してください。

2. #F、#D — 数値を基数 2 浮動小数点形式で保持するには、float * で #F を使用するかまたは double * で #D を使用します。詳細は、“数値リンクの使用” を参照してください。

3. 1C、2C、4C — このリンクで渡されるすべての文字列は最初の NULL 文字で切り捨てられます。詳細は、“NULL で終了する文字列を C リンク・タイプで渡す” を参照してください。

4. 4B、4C、4J — wchar_t が一般的に 32 ビットであっても、Caché では 16 ビットのみを使用して各 Unicode 文字を格納するため、これらのリンクは wchar_t の使用を指定する既存のコードまたはシステム・インタフェースとやり取りするときにのみ役立ちます。

構造体と引数のプロトタイプ定義 (インターシステムズ内部定義を含む) は、インクルード・ファイル cdzf.h にあります。

数値リンクの使用

数値リンク・タイプは、以下のデータ型用に提供されています。

数値引数が指定されると、Caché では文字列の入力引数が許可されます。文字列が渡されると、先頭の数字が文字列から解析されて数値が派生します。先頭の数字がない場合は、値 0 が受け取られます。つまり、"2DOGS" は 2.0 として受け取られますが、"DOG" は 0.0 として受け取られます。整数の引数は切り捨てられます。例えば、"2.1DOGS" は 2 として受け取られます。詳細は、"ObjectScript の使用法" の “文字列から数値への変換” を参照してください。

既定では、Caché は、10 進法で小数を格納します。例えば、数値 1.3 は 13*.10 として格納されます。一方、大半の高レベル言語は、2 進数の形式で小数を格納します (2 進数と 2 の累乗の積)。引数を f (float *) または d (double *) として記述する場合、Caché は、入力時に 10 進数値を 2 進数値に変換し、出力時に 10 進数値に戻します。この変換により、値に若干の誤差が生じる可能性があります。

Caché は標準の IEEE 形式の 64 ビット浮動小数点を作成する $DOUBLE 関数をサポートします。これらの数は、精度を失うことなく外部関数と Caché 間で渡すことができます (外部関数が 64 ビットの double ではなく 32 ビットの float を使用する場合を除く)。出力では、IEEE 形式の使用は、接頭語 # を F または D の引数タイプへ追加すると、指定できます。例えば、"i#D" は整数の入力引数 1 つと、64 ビット浮動小数点出力引数 1 つに引数リストを指定します。

NULL で終了する文字列を C リンク・タイプで渡す

このリンク・タイプは、Caché が NULL ($CHAR(0)) 文字を含む文字列を送信しないことがわかっている場合にのみ使用します。このデータ型を使用する際は、C 関数は、文字列が長い場合でも、Caché によって渡される文字列を最初の NULL 文字で切り捨てます。例えば、文字列 "ABC"_$CHAR(0)_"DEF" は、"ABC" に切り捨てられます。

数値文字列を返すために 3 つすべてのリンク・タイプを使用する短いコールアウト・ライブラリを以下に示します。

C リンクを使用した NULL 終了文字列渡し

以下の 3 つの関数それぞれは、ランダム整数を生成して最大 6 桁の数値文字列に変換し、C リンクを使用してその文字列を返します。

#define ZF_DLL   // Required when creating a Callout library.
#include <cdzf.h>
#include <stdio.h>
#include <wchar.h>   // Required for 16-bit and 32-bit strings

int get_sample(char* retval) {  // 8-bit, null-terminated
   sprintf(retval,"%d",(rand()%1000000));
   return ZF_SUCCESS;
}

int get_sample_W(unsigned short* retval) {  // 16-bit, null-terminated
   swprintf(retval,6,L"%d",(rand()%1000000));
   return ZF_SUCCESS;
}

int get_sample_H(wchar_t* retval) {  // 32-bit, null-terminated
   swprintf(retval,6,L"%d",(rand()%1000000));
   return ZF_SUCCESS;
}

ZFBEGIN
ZFENTRY("GetSample","1C",get_sample)
ZFENTRY("GetSampleW","2C",get_sample_W)
ZFENTRY("GetSampleH","4C",get_sample_H)
ZFEND

短い計算文字列を B リンク・タイプで渡す

cdzf.h コールアウト・ヘッダ・ファイルは、短い文字列 (インターシステムズの従来の文字列型) を表す計算文字列構造 ZARRAY、ZWARRAY、および ZHARRAY を定義します。これらの構造は、文字要素の配列 (それぞれ、8 ビット、16 ビット Unicode、または 32 ビット wchar t) および配列内の要素の数を指定する short 整数 (最大値は 32,768) を含みます。以下はその例です。

typedef struct zarray {
    unsigned short len;
    unsigned char data[1]; /* 1 is a dummy value */
   } *ZARRAYP;

以下はその説明です。

• len — 配列の長さが格納されます。

• data — 文字データを格納する配列です。要素タイプは、ZARRAY は unsigned char、ZWARRAY は unsigned short、ZHARRAY は wchar_t です。

B リンクは、3 つの配列構造に対応して、ポインタ型 ZARRAYP、ZWARRAYP、および ZHARRAYP を指定します。返される配列の最大サイズは 32,767 文字です。

引数の最大合計長さは、1 文字あたりのバイト数に依存します (“$ZF ヒープの構成” を参照)。

数値文字列を返すために 3 つすべてのリンク・タイプを使用するコールアウト・ライブラリを以下に示します。

B リンクを使用した計算文字列渡し

以下の 3 つの関数それぞれは、ランダム整数を生成して最大 6 桁の数値文字列に変換し、B リンクを使用して文字列を返します。

#define ZF_DLL   // Required when creating a Callout library.
#include <cdzf.h>
#include <stdio.h>
#include <wchar.h>   // Required for 16-bit and 16-bit characters

int get_sample_Z(ZARRAYP retval) {  // 8-bit, counted
   unsigned char numstr[6];
   sprintf(numstr,"%d",(rand()%1000000));
   retval->len = strlen(numstr);
   memcpy(retval->data,numstr,retval->len);
   return ZF_SUCCESS;
}

int get_sample_ZW(ZWARRAYP retval) {  // 16-bit, counted
   unsigned short numstr[6];
   swprintf(numstr,6,L"%d",(rand()%1000000));
   retval->len = wcslen(numstr);
   memcpy(retval->data,numstr,(retval->len*sizeof(unsigned short)));
   return ZF_SUCCESS;
}

int get_sample_ZH(ZHARRAYP retval) {  // 32-bit, counted
   wchar_t numstr[6];
   swprintf(numstr,6,L"%d",(rand()%1000000));
   retval->len = wcslen(numstr);
   memcpy(retval->data,numstr,(retval->len*sizeof(wchar_t)));
   return ZF_SUCCESS;
}


ZFBEGIN
ZFENTRY("GetSampleZ","1B",get_sample_Z)
ZFENTRY("GetSampleZW","2B",get_sample_ZW)
ZFENTRY("GetSampleZH","4B",get_sample_ZH)
ZFEND

標準的な計算文字列を J リンク・タイプで渡す

callin.h ヘッダ・ファイルは、標準的な InterSystems 文字列を表す計算文字列構造 CACHE_EXSTR を定義します。この構造は、文字要素の配列 (8 ビット、16 ビット Unicode、または 32 ビット wchar t) および配列内の要素の数を指定する int 値 (最大値は 3,641,144) を含みます。

typedef struct {
   unsigned int   len;         /* length of string */
   union {
      Callin_char_t  *ch;      /* text of the 8-bit string */
      unsigned short *wch;     /* text of the 16-bit string */
      wchar_t        *lch;     /* text of the 32-bit string */
/* OR unsigned short *lch   if 32-bit characters are not enabled */
   } str;
} CACHE_EXSTR, *CACHE_EXSTRP;

次の 2 つの InterSystems コールイン関数 ("コールイン API の使用法" の “コールイン関数リファレンス” を参照してください) は、CACHE_EXSTR の作成または削除に使用されます。

• CacheExStrKill — CACHE_EXSTR 文字列に関連付けられているストレージを解放します。

• CacheExStrNew[W][H] — 文字列に対して要求されたストレージの容量を割り当て、CACHE_EXSTR 構造に、構造の長さおよび構造の値フィールドへのポインタを埋め込みます。

これらの関数の使用方法のデモンストレーションは、以下の例を参照してください。

数値文字列を返すために 3 つすべてのリンク・タイプを使用するコールアウト・ライブラリを以下に示します。

J リンクを使用した文字列渡し

以下の 3 つの関数それぞれは、ランダム整数を生成して最大 6 桁の数値文字列に変換し、J リンクを使用して文字列を返します。

#define ZF_DLL   // Required when creating a Callout library.
#include <cdzf.h>
#include <stdio.h>
#include <wchar.h>
#include <callin.h>

int get_sample_L(CACHE_EXSTRP retval) {  // 8-bit characters
   Callin_char_t numstr[6];
   size_t len = 0;
   sprintf(numstr,"%d",(rand()%1000000));
   len = strlen(numstr);
   CACHEEXSTRKILL(retval);
   if (!CACHEEXSTRNEW(retval,len)) {return ZF_FAILURE;}
   memcpy(retval->str.ch,numstr,len);   // copy to retval->str.ch
   return ZF_SUCCESS;
}

int get_sample_LW(CACHE_EXSTRP retval) {  // 16-bit characters
   unsigned short numstr[6];
   size_t len = 0;
   swprintf(numstr,6,L"%d",(rand()%1000000));
   len = wcslen(numstr);
   CACHEEXSTRKILL(retval);
   if (!CACHEEXSTRNEW(retval,len)) {return ZF_FAILURE;}
   memcpy(retval->str.wch,numstr,(len*sizeof(unsigned short)));   // copy to retval->str.wch
   return ZF_SUCCESS;
}

int get_sample_LH(CACHE_EXSTRP retval) {  // 32-bit characters
   wchar_t numstr[6];
   size_t len = 0;
   swprintf(numstr,6,L"%d",(rand()%1000000));
   len = wcslen(numstr);
   CACHEEXSTRKILL(retval);
   if (!CACHEEXSTRNEW(retval,len)) {return ZF_FAILURE;}
   memcpy(retval->str.lch,numstr,(len*sizeof(wchar_t)));   // copy to retval->str.lch
   return ZF_SUCCESS;
}

ZFBEGIN
ZFENTRY("GetSampleL","1J",get_sample_L)
ZFENTRY("GetSampleLW","2J",get_sample_LW)
ZFENTRY("GetSampleLH","4J",get_sample_LH)
ZFEND

短い文字列の $ZF ヒープの構成

$ZF ヒープは、すべての $ZF の短い文字列入力および出力パラメータに割り当てられる仮想メモリ領域です。これは、以下の Caché システム設定によって制御されます。

• ZFString は、1 つの文字列パラメータに対して使用が許可される文字数です。このために実際に必要なバイト数は、使用している文字が 8 ビット文字か、16 ビット Unicode 文字か、UNIX® 上の 32 ビット文字かによって異なります。この設定で許可されている範囲は、0 から 32767 文字です。既定は、0 であり、最大値を使用することを示します。

• ZFSize は、Caché がすべての $ZF 入力および出力パラメータに割り当てる合計バイト数です。この設定で許可されている範囲は、0 から 270336 バイトです。0 (既定の設定) は、Caché が ZFString の値に基づいて適切な値を計算することを示します。

以下のように ZFSize (合計バイト数) を ZFString (文字列あたりの最大文字数) に基づいて計算します。

      ZFSize = (<bytes per character> * ZFString) + 2050