$ZF (ObjectScript)
構文
$ZF("function_name",args)
引数
引数 | 説明 |
---|---|
function_name | 呼び出す関数の名前 |
args | オプション — 関数に渡される一連の引数値 |
概要
さまざまな形式の $ZF 関数を使用して、非 ObjectScript プログラム (シェルやオペレーティング・システムのコマンドなど) や、ObjectScript コードから関数を呼び出すことができます。他言語で記述された関数へのリンクやインタフェースを InterSystems IRIS に定義し、$ZF を使用して ObjectScript コードから呼び出すことができます。
その他の $ZF 関数
$ZF は、以下のように使用することもできます。
-
プログラムあるいはコマンドを実行する子プロセスを作成します。$ZF(-100)。
-
ダイナミック・リンク・ライブラリ (DLL) をロードし、そのライブラリから関数を実行します。$ZF(-3)、$ZF(-4)、$ZF(-5)、および $ZF(-6)。
$ZF のこれらの実装は、最初の引数に負の数を指定します。これらについては、それぞれのリファレンスのページで説明しています。
引数
function_name
引用符で囲まれた呼び出す関数の名前、または負の数。
args
args 引数の形式は、arg1, arg2, arg3, ...argn です。この引数は、引数が渡される方法の説明、および呼び出している C 関数へのエントリ・ポイントなどの項目から構成されます。
$ZF を使用して UNIX® システム・サービスを呼び出す
InterSystems IRIS は、$ZF からの UNIX® システム呼び出しを使用するための、エラー・チェック機能をサポートしています。これらの呼び出しにより、非同期のイベントの確認や $ZF でのアラーム・ハンドラの設定ができます。これらの UNIX® 機能を使用することにより、実際のエラー、<CTRL-C> の割り込み、および再起動が必要な呼び出しをそれぞれ区別できます。
関数宣言は、iris-cdzf.h に含まれており、以下のテーブルに示されているとおりです。
宣言 | 目的 | メモ |
---|---|---|
int sigrtclr(); | 再試行フラグのクリア | sigrtchk() を使用する前に 1 回呼び出します。 |
int dzfalarm(); | 新規 SIGALRM ハンドラの構築 | $ZF にエントリする際に、前のハンドラが自動的に保存されます。終了すると、自動的にリストアされます。ユーザ・プログラムで、他のシグナル処理を変更しないでください。 |
int sigrtchk(); | 非同期イベントのチェック |
これは、open()、close()、read()、write()、ioctl()、pause() のいずれかのシステム呼び出しが失敗した場合、またはプロセスがシグナルを受信したときの呼び出しが失敗した場合に、必ず呼び出す必要があります。これは、ユーザが次に何をするべきかを示すコードを返します。 -1 シグナルではありません。入出力エラーを調べてください。errno 変数の内容を参照してください。 0 他のシグナルです。割り込みが生じた時点から処理を再開してください。 1 SIGINT/。SIGTERM "return 0" で $ZF を終了します。システムは、これらのシグナルを適切にトラップします。 |
デバイスを制御する通常の $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 your job. */
Do cleanup work
return 1 or 0;
}
}
ELSE { break; }
/* Code to handle the normal situation: */
/* open() system call succeeded */
dzfalarm() 経由以外でシグナル・ハンドラを設定しないでください。
エンコード・システム間で文字列を変換する
InterSystems IRIS は、$ZF 引数タイプ、t (または T) 経由の入出力変換をサポートします。これは、以下の形式で指定できます。
引数 | 目的 |
---|---|
t | 現在のプロセス入出力変換オブジェクトを指定します。 |
t// | 既定のプロセス入出力変換テーブル名を指定します。 |
t/name/ | 特定の入出力変換テーブル名を指定します。 |
$ZF は、以下の C 構造にあるバイト文字列経由で、変換された文字列を外部プロシージャに移します。
typedef struct zarray {
unsigned short len;
unsigned char data[1]; /* 1 is a dummy value */
} *ZARRAYP;
これは、b (または B) 引数タイプに使用された構造でもあります。
以下の $ZF サンプル関数は、可逆変換を実行します。
#include iris-cdzf.h
extern int trantest();
ZFBEGIN
ZFENTRY("TRANTEST","t/SJIS/ T/SJIS/",trantest)
ZFEND
int trantest(inbuf,outbuf);
ZARRAYP inbuf; /* Buffer containing string that was converted from
internal InterSystems IRIS encoding to SJIS encoding before it
was passed to this function */
ZARRAYP outbuf; /* Buffer containing string in SJIS encoding that will
be converted back to internal InterSystems IRIS encoding before
it is passed back into the InterSystems IRIS environment */
{
int i;
/* Copy data one byte at a time from the input argument buffer
to the output argument buffer */
for (i = 0; i < inbuf->len; i++)
outbuf->data[i] = inbuf->data[i];
/* Set number of bytes of data in the output argument buffer */
outbuf->len = inbuf->len;
return 0; /* Return success */
}
概念的には、データは外部プロシージャがデバイスであるかのように、$ZF 外部プロシージャへ流れ込んだり、また外部プロシージャから流れ出たりします。入出力変換の出力要素は、データが InterSystems IRIS 環境から "出ていく" ので、外部プロシージャに渡されるデータとして使用されます。入出力変換の入力要素は、データが InterSystems IRIS 環境に "入る" ので、外部プロシージャから渡されるデータとして使用されます。
入出力変換の出力要素が未定義で、アプリケーションがその入出力変換を使用して NULL 文字列以外のデータを渡そうとする場合、データの変換方法が不明であるため、InterSystems IRIS はエラーを返します。
入出力変換の入力要素が未定義で、タイプ文字列の引数が入出力変換を $ZF 出力引数に関連付ける場合、未定義の変換を使用する出力引数は無意味なので、InterSystems IRIS はエラーを返します。
ゼロで終了する Unicode 文字列、および Unicode 計算文字列
$ZF 関数は、ゼロで終了する Unicode 文字列、および Unicode 計算文字列の引数タイプをサポートします。
ゼロ で終了する Unicode 文字列、および Unicode 計算文字列の引数タイプは、以下のコードを持ちます。
引数 | 目的 |
---|---|
w | ゼロで終了する Unicode 文字列へのポインタ |
s | Unicode 計算文字列へのポインタ |
両方の引数タイプで、Unicode 文字の C データ型は unsigned short です。ゼロで終了する Unicode 文字列のポインタは、以下のように宣言されます。
unsigned short *p;
Unicode 計算文字列に対するポインタは、以下の C 構造に対するポインタとして宣言されます。
typedef struct zwarray {
unsigned short len;
unsigned short data[1]; /* 1 is a dummy value */
} *ZWARRAYP;
例えば以下のようになります。
ZWARRAYP *p;
len フィールドには、Unicode 文字配列の長さが格納されます。
data フィールドには、Unicode 計算文字列の文字が格納されます。Unicode 文字列の最大値は、$ZF 文字列の最大値です。これは、更新できる構成パラメータで、既定は 32767 です。
各 Unicode 文字の長さは 2 バイトです。InterSystems IRIS は返される可能性のある最大長文字列のスペースを予約するため、出力引数として Unicode 文字列を宣言する際は、この文字の長さを考慮することが重要です。既定の文字列サイズを使用する場合、1 つの Unicode 文字列引数で使用するメモリの合計は以下のように計算します。
32767 (最大文字数) * 2 (1 文字あたりのバイト数) = 65534 (合計バイト)
この値は、すべての $ZF 引数に割り当てられる既定の最大メモリ領域の値 (67584) とほぼ同じ値です。この最大 $ZF ヒープ領域は、更新可能な構成パラメータでもあります。
エラー・メッセージ
$ZF ヒープ領域がすべて使用されている場合、$ZF は <OUT OF $ZF HEAP SPACE> エラーを発行します。$ZF 文字列スタックがすべて使用されている場合、$ZF は <STRINGSTACK> エラーを発行します。$ZF がバディブロックを割り当てることができない場合、<STORE> エラーを発行します。