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

ZFEntry テーブルの作成

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

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

   ZFENTRY(zfname,linkage,entrypoint)

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

コールアウト・ライブラリを作成するには、ライブラリ関数を見つけるための内部の GetZFTable 関数を生成するスイッチである #define ZF_DLL 指示文をコードに含める必要があります。コールアウト・ライブラリがロードされると、InterSystems IRIS はこの関数を呼び出して後続のライブラリ関数名の検索用にライブラリを初期化します。

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 — 数値引数が指定されると、InterSystems IRIS では文字列の入力引数が許可されます。詳細は、“数値リンクの使用” を参照してください。

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

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

4. 4B、4C、4J — wchar_t は通常 32 ビットですが、InterSystems IRIS では各 Unicode 文字を格納するのに 16 ビットのみを使用します。大きい wchar_t 値を含む出力引数は、$ZF の戻り値に割り当てるために UTF-16 に変換されます。UTF-16 を含む文字列 (サロゲート・ペア) は、$ZF 入力引数のために wchar_t に展開されます。wchar_t の真の値には、ObjectScript 関数 $WASCII() および $WCHAR() を使用してアクセスできます。

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

数値リンクの使用

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

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

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

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

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

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

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

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

#define ZF_DLL   // Required when creating a Callout library.
#include <iris-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 リンク・タイプで渡す

iris-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 <iris-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 リンク・タイプで渡す

iris-callin.h ヘッダ・ファイルは、標準的な InterSystems IRIS 文字列を表す計算文字列構造 IRIS_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;
} IRIS_EXSTR, *IRIS_EXSTRP;

IRIS_EXSTR データ構造は、コールイン API から関数で操作します (低レベルの InterSystems 関数呼び出しのライブラリ。詳細は、"コールイン API の使用法" の “コールイン関数リファレンス” を参照してください。名前はよく似ていますが、コールイン API とコールアウト SDK はまったく別の製品です)。

IRIS_EXSTR のインスタンスを作成および破棄するには、以下の関数を使用します。

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

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

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

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

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

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

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

int get_sample_LW(IRIS_EXSTRP retval) {  // 16-bit characters
   unsigned short numstr[6];
   size_t len = 0;
   swprintf(numstr,6,L"%d",(rand()%1000000));
   len = wcslen(numstr);
   IRISEXSTRKILL(retval);
   if (!IRISEXSTRNEW(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(IRIS_EXSTRP retval) {  // 32-bit characters
   wchar_t numstr[6];
   size_t len = 0;
   swprintf(numstr,6,L"%d",(rand()%1000000));
   len = wcslen(numstr);
   IRISEXSTRKILL(retval);
   if (!IRISEXSTRNEW(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 の短い文字列入力および出力パラメータに割り当てられる仮想メモリ領域です。これは、以下の InterSystems IRIS システム設定によって制御されます。

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

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

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

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

ワースト・プラクティス

ほぼすべてのルーチンはコールアウト SDK で呼び出すことができますが、コールアウト SDK は数学関数で使用するのが最適です。また、InterSystems IRIS I/O でうまく処理されない外部デバイスへのインタフェース、または InterSystems IRIS インタフェースが存在しないシステム・サービスの場合にも効果的に使用することができます。

以下の動作によって重大な問題が発生する可能性があります。

• 自身に属していないメモリへのアクセス

  メモリ・アクセス違反は、InterSystems IRIS によって処理され、InterSystems IRIS 内のバグとして扱われます。

• トラップによって処理されるその他のエラーの発生

  トラップによって処理されるエラー (ほとんどのプラットフォーム上でのゼロによる除算など) も InterSystems IRIS 内のバグとして扱われます。

• プロセスの優先度の変更

  InterSystems IRIS は、InterSystems IRIS を実行する他のプロセスと対話する必要があります。優先度を下げると、上げるのと同様に問題が発生する場合があります。例えば、プロセスが CPU を解放する直前にスピン・ロックで保護されたリソースを取得することを考えてみましょう。優先度が低すぎると、高い優先度のその他のプロセスがリソースを奪い合い、事実上、スピン・ロックを解除できるようにするプロセスの実行を妨げます。

• 中断のマスク

  インタロックを実装するために中断を短時間マスクする場合がありますが、中断をマスクしたままにしないように十分注意する必要があります。

• 削除できないリソースを作成または開く

  ファイルを開いて malloc を使用してメモリを割り当てることは問題ありません。それらのリソースはプロセスの終了時に閉じられるかまたは解放されます。2 番目のスレッドを作成すると、2 番目のスレッドが InterSystems IRIS プロセスの終了前に正常に終了することを保証できないため、2 番目のスレッドは作成しないでください。

• opaque 以外のオブジェクトを ObjectScript 以外のコードで返す

  コード内のメモリのブロックを malloc して、それを読み取るために $VIEW(address,−3,size) を使用できると考えないでください。また、ObjectScript 以外のコードに malloc ブロックを戻さないでください。コードは opaque ハンドルを返し、後で opaque ハンドルを受け取った時に使用する前に有効であることを確認する必要があります。

• プロセスの終了

  exit だけを呼び出すことはしないでください。常に ZF_SUCCESS または ZF_FAILURE のいずれかと共に返します (これらの値の実装は InterSystems IRIS プラットフォーム間で異なることに留意してください)。

• exec のいずれかのバージョンの呼び出しによる終了

  子プロセス内で fork してから exec を呼び出すことはできますが、必ず親は InterSystems IRIS に返り、子プロセスは InterSystems IRIS に返らないようにしてください。

• プロセスでのエラー処理の振る舞いの変更

  Windows とは異なり、UNIX® システムでは、現在の内部フレームのローカル・エラー処理のみを確立できます。

UNIX® シグナル処理のエラーの処理

UNIX® および関連するオペレーティング・システムで実行中の場合、システム呼び出しの中には、open、read、write、close、ioctl、および pause などのシグナルをプロセスが受け取ると、失敗するものがあります。関数がこれらのシステム呼び出しを使用する場合、実際のエラー、Ctrl-C、再起動を必要とする呼び出しと区別できるように、コードを記述する必要があります。

以下の関数により、非同期のイベントの確認や $ZF でのアラーム・ハンドラの設定ができます。関数の宣言は、iris-cdzf.h に組み込まれます。

一部のデバイスの制御に使用される一般的な $ZF 関数は、以下の擬似コードと同様のロジックを使用します。

if ((fd = open(DEV_NAME, DEV_MODE)) < 0) {
    Set some flags
    Call zferror
    return 0;
}

プロセスがシグナルを受け取ると、open システム呼び出しは失敗する可能性があります。通常、これはエラーではないため、処理を再開できます。しかし、シグナルによっては他の処理が必要な場合もあります。すべての可能性を考慮するために、以下の C コードを使用することを検討してください。

sigrtclr();
while (TRUE) {
    if (sigrtchk() == 1) return 1 or 0;
    if ((fd = open(DEV_NAME, DEV_MODE)) < 0) {
        switch (sigrtchk()) {
             case -1:
                /* This is probably a real device error */
                Set some flags
                Call zferror
                return 0;
            case 0:
                /* A innocuous signal was received. Restart. */
                continue;
            case 1:
                /* Someone is trying to terminate the job. */
                Do cleanup work
                return 1 or 0;
        }
    }
    else break;
}
/*
Code to handle the normal situation:
open() system call succeeded
*/