$DLLEXEC2(DLL実行関数)
ユーザが作成したユーザ関数を実行します。$DLLEXEC2で実行するユーザ関数とアクセス定義ファイルとの間のデータの受け渡しは、配列変数を使用します。ユーザ関数内で配列変数にアクセスするためには、Asset Consoleが提供するマクロを使用します。
- 〈このページの構成〉
-
形式
$DLLEXEC2(DLLオブジェクト,関数名,配列変数名1(,配列変数名2(,…)))
指定する値
-
DLLオブジェクト
$DLLLOADで求めたDLLオブジェクトの変数名を指定します。
-
関数名
実行する関数の名称を、定数または変数で指定します。定数を指定する場合は、「'(シングルクォーテーション)」で囲みます。
-
配列変数名
関数に渡す情報を設定した配列変数名、または関数で実行した結果を取得する配列変数名を指定します。
使用するDLLのインターフェース
$DLLEXEC2で呼び出す関数の形式を次に示します。
int 関数名(int argc //スクリプトで指定した配列変数の数 ,void** argv //スクリプトで指定した配列変数群の先頭アドレス )
スクリプトで指定した配列変数は、指定した順(左から)で、argvの0番配列から順番に格納されています。そのため、配列変数名1はargv[0]、配列変数名2はargv[1]として関数内で処理します。
関数の戻り値が負数の場合には、同じDLLにユーザが用意したaim_getmessage関数を実行し、メッセージが書き込まれていたら、その内容をAsset Consoleのログに書き込み、スクリプトの実行を中断します。
終了状態
処理の終了状態とその内容を次に示します。
終了状態 |
内容 |
---|---|
NORMAL |
正常終了(関数の戻り値が0の場合) |
NODATA |
警告付き終了(関数の戻り値が1の場合) |
ERROR |
異常終了(関数の戻り値が正数の場合) |
スクリプト中断 |
次のどちらかを示す
|
注意事項
組み込み関数$DLLEXEC2で呼び出すユーザ関数を実装したDLLを、あらかじめ用意しておく必要があります。
記述例
「sample.dll」をロードし、集計関数「FunctionSum」を実行する場合の記述例を次に示します。この例では、ロードした「sample.dll」に引数「10」、「20」、「30」を設定して「FunctionSum」を実行し、その結果を出力することを示しています。
[SET_VALUE] DLLOBJ = $DLLLOAD('sample.dll') STATUS = $GETSTATUS() [IF] STATUS != NORMAL [THEN] [SET_VALUE] $ECHO('DLL LOAD ERROR') $EXIT(3) [IF_END] [SET_VALUE] $SETARRAY(INPUT, '10') $SETARRAY(INPUT, '20') $SETARRAY(INPUT, '30') $DLLEXEC2(DLLOBJ,'FunctionSum',INPUT,OUTPUT) STATUS = $GETSTATUS() [IF] STATUS = NORMAL [THEN] [SET_VALUE] VAL = $GETARRAY(OUTPUT, 1) MSG = 'OUTPUT = ' +VAL $ECHO(MSG) [ELSE] [SET_VALUE] VAL = $DLLMSG(DLLOBJ) MSG ='DLLEXEC FunctionSum ERROR (' +VAL+ ')' $ECHO(MSG) [IF_END] [SET_VALUE] $DLLFREE(DLLOBJ)
$DLLEXEC2で実行可能なユーザ関数の作成
$DLLEXEC2で実行するユーザ関数が、スクリプトとの間でデータの受け渡しが必要ない場合は、一般的な手順でDLLを作成できます。
ユーザ関数がスクリプトから情報を受け取ったり、ユーザ関数の処理結果をスクリプトの配列に設定したりする場合には、スクリプトの配列変数にアクセスするために、Asset Consoleが提供する専用の関数を使用する必要があります。Asset Consoleでは、これらの配列変数へのアクセス用関数をマクロとして提供しています。
マクロはCおよびC++言語用のヘッダファイル「jamScriptAPI.h」に定義されています。このヘッダファイルをインクルードすることで、アクセス定義ファイル中の組み込み関数と同じインターフェースで配列を操作できます。
なお、DLLに実装された、配列操作のマクロを使用した関数を実行できるのは、$DLLEXEC2からだけです。
jamScriptAPI.hの格納先を次に示します。
Asset Consoleのインストール先フォルダ\sdk\include
jamScriptAPI.hに定義されたマクロの一覧を次に示します。
DLL作成時に使用できる各マクロについて説明します。
■$CLEARARRAY(配列初期化マクロ)
指定した配列に格納されている情報をすべて削除して、配列を初期化します。
- 形式(相当関数形式)
int $CREARARRAY(void** argv,void* array);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(ユーザ関数の引数)
-
- 戻り値
-
戻り値
内容
0
正常終了
-1
エラー※
- コーディング例
-
スクリプトで指定した、1番目の配列を初期化するコーディング例を次に示します。
int DllFunc8(int argc,void** argv){ int rc; rc = $CLEARARRAY(argv,argv[0]); if(rc)return-1; return 0; }
■$GETARRAY(配列からのデータ取得マクロ)
配列に格納されている情報から、指定した位置番号の情報を取得します。
- 形式
char* $GETARRAY(void** argv,void* array,int pos);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(ユーザ関数の引数)
-
pos
情報を取得する配列内の位置番号(「1」から開始)
-
- 戻り値
-
戻り値
内容
指定した配列の情報(文字列)
正常終了
NULL
エラー※、または指定した位置番号の情報が存在しない
- コーディング例
-
スクリプトで指定した1番目の配列の、1番目の情報を取得するコーディング例を次に示します。
int DllFunc3(int argc,void** argv){ void *data; data = $GETARRAY(argv,argv[0],1); if(!data) if($GETSTATUS(argv) != JAM_SCRIPTAPI_NORMAL && $GETSTATUS(argv) != JAM_SCRIPTAPI_NODATA) return -1; return 0; }
■$GETARRAYBYKEY(キー指定による配列からのデータ取得マクロ)
スクリプト側で組み込み関数$SETARRAYBYKEYを使用して作成した配列や、ユーザ関数内で$SETARRAYBYKEYマクロを使用して作成したキー付き配列から、指定したキーを持つ情報を取得します。同一のキーを持つ要素が存在する場合、同一キーの何番目の要素を取り出すかを示す、キー内配列番号を指定します。
- 形式
char* $GETARRAYBYKEY(void** argv,void* array,char* key,int pos);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(ユーザ関数の引数)
-
key
キー
-
pos
キー内配列番号(「1」から開始)
-
- 戻り値
-
戻り値
内容
キーで指定した配列の情報(文字列)
正常終了
NULL
エラー※、または指定したキー内配列番号の情報が存在しない
- コーディング例
-
スクリプトで指定した1番目の配列から、キー「key1」で格納された1番目のキー内配列番号の情報を取得するコーディング例を次に示します。
int DllFunc4(int argc,void** argv){ void *data; data = $GETARRAYBYKEY(argv,argv[0],"key1",1); if(!data) if($GETSTATUS(argv) != JAM_SCRIPTAPI_NORMAL && $GETSTATUS(argv) != JAM_SCRIPTAPI_NODATA) return -1; return 0; }
■$GETARRAYLENGTH(配列の要素数の取得マクロ)
指定した配列の要素数を取得します。
- 形式
int $GETARRAYLENGTH(void** argv,void* array);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(ユーザ関数の引数)
-
- 戻り値
-
戻り値
内容
配列数(0以上の数値)
正常終了
-1
エラー※
- コーディング例
-
スクリプトで指定した1番目の配列の配列要素数を取得するコーディング例を次に示します。
int DllFunc10(void* obj,void* functbl,int argc,void** argv){ int len; len = $GETARRAYLENGTH(argv,argv[0]); if (len<0) return -1; return 0; }
■$GETARRAYNAME(配列名の取得マクロ)
指定した配列の配列変数名を取得します。
- 形式
char* $GETARRAYNAME(void** argv,void* array);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(ユーザ関数の引数)
-
- 戻り値
-
戻り値
内容
配列変数名(文字列)
正常終了
NULL
エラー※
- コーディング例
-
スクリプトで指定した1番目の配列の配列変数名を取得するコーディング例を次に示します。
int DllFunc9(int argc,void** argv){ char* name; name = $GETARRAYNAME(argv,argv[0]); if(!name) return -1; return 0; }
■$GETINITAREA(aim_init関数の戻り値(インスタンス)の取得マクロ)
aim_init関数の戻り値であるインスタンスを取得します。
- 形式
void * $GETINITAREA(void** argv);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
- 戻り値
-
aim_init関数の戻り値(インスタンス)です。
- コーディング例
-
aim_init関数の戻り値を取得するコーディング例を次に示します。
int DllFunc(int argc, void** argv){ USER_HANDLE* obj; obj = $GETINITAREA(argv); return 0; }
■$GETKEYFROMARRAY(キー情報の取得マクロ)
キー付きで配列に格納されている情報から、指定した配列番号の情報が持つキー情報を取得します。
- 形式
char* $GETKEYFROMARRAY(void** argv,void* array,int pos);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(ユーザ関数の引数)
-
pos
情報を取得する配列要素の配列番号(「1」から開始)
-
- 戻り値
-
戻り値
内容
キー情報(文字列)
正常終了※1
NULL
エラー※2、または指定した配列番号の値が存在しない
- コーディング例
-
スクリプトで指定した3番目の配列の、1番目の配列要素に格納されているキー情報を取得するコーディング例を次に示します。
int DllFunc7(void* obj,void* functbl,int argc,void** argv){ void *key; key = $GETKEYFROMARRAY(argv,argv[2],1); if(!key) if($GETSTATUS(argv) != JAM_SCRIPTAPI_NORMAL && $GETSTATUS(argv) != JAM_SCRIPTAPI_NODATA) return -1; return 0; }
■$GETSTATUS(マクロの終了状態の取得マクロ)
処理の終了状態を取得します。
- 形式
int $GETSTATUS(void** argv);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
- 戻り値
-
戻り値
内容
JAM_SCRIPTAPI_NORMAL
正常終了
JAM_SCRIPTAPI_DUPLICATE
キー値の重複
JAM_SCRIPTAPI_NODATA
該当配列データなし
JAM_SCRIPTAPI_INSUFFICIENTMEMORY
処理に必要なメモリの不足
JAM_SCRIPTAPI_ILLEGAL
呼び出しインターフェース不正
JAM_SCRIPTAPI_ERROR
上記以外の内部エラーの発生
- コーディング例
-
$GETARRAY(配列からのデータ取得マクロ)のコーディング例を参照してください。
■$SETARRAY(配列へのデータ設定マクロ)
配列に情報を追加します。
- 形式
int $SETARRAY(void** argv,void* array,char* value);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(情報を追加するユーザ関数の引数)
-
value
追加する情報(文字列)
-
- 戻り値
-
戻り値
内容
0
正常終了
-1
エラー※
- コーディング例
-
スクリプトで指定した2番目の配列に、情報「data1」で配列要素を追加するコーディング例を次に示します。
int DllFunc1(int argc, void** argv){ int rc; rc = $SETARRAY(argv,argv[1],"data1"); if(rc) return -1; return 0; }
■$SETARRAYBYKEY(配列へのキー付きデータ設定マクロ)
キー付きで配列に情報を追加します。
- 形式
int $SETARRAYBYKEY(void** argv,void* array,char* key,char* value);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(情報を追加するユーザ関数の引数)
-
key
キー
-
value
追加する情報(文字列)
-
- 戻り値
-
戻り値
内容
0
正常終了
-1
エラー※
- コーディング例
-
スクリプトで指定した2番目の配列に、キー値「key1」、情報「data1」で配列要素を追加するコーディング例を次に示します。
int DllFunc2(int argc,void** argv){ int rc; rc = $SETARRAYBYKEY(argv,argv[1],"key1","data1"); if(rc) return -1; return 0; }
■$UPDARRAY(配列データの更新マクロ)
配列変数の配列要素の値を更新します。配列要素は、配列番号で指定します。
- 形式
int $UPDARRAY(void** argv,void* array,int pos,char* value);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(配列要素を更新するユーザ関数の引数)
-
pos
情報を更新する配列要素の配列番号(「1」から開始)
-
value
更新する情報(文字列)
-
- 戻り値
-
戻り値
内容
0
正常終了
-1
エラー※
- コーディング例
-
スクリプトで指定した2番目の配列の、2番目の配列要素の値を「data2」に更新するコーディング例を次に示します。
int DllFunc5(int argc,void** argv){ int rc; rc = $UPDARRAY(argv,argv[1],2,"data2"); if(rc) if($GETSTATUS(argv) != JAM_SCRIPTAPI_NORMAL && $GETSTATUS(argv) != JAM_SCRIPTAPI_NODATA) return -1; return 0; }
■$UPDARRAYBYKEY(キー付き配列データの更新マクロ)
配列変数の配列要素の値を更新します。配列要素は、キーおよびキー内の配列番号で指定します。
- 形式
int $UPDARRAYBYKEY(void ** argv,void* array,char* key,int pos,char* value);
- 引数
-
-
argv
スクリプトで指定した配列変数群の先頭アドレス
-
array
配列変数群の要素の一つ(配列要素を更新するユーザ関数の引数)
-
key
キー
-
pos
キー内配列番号(「1」から開始)
-
value
更新する情報(文字列)
-
- 戻り値
-
戻り値
内容
0
正常終了
-1
エラー※
- コーディング例
-
スクリプトで指定した2番目の配列で、キー「key1」で格納された1番目の配列要素の値を「data1」に更新するコーディングの例を次に示します。
int DllFunc6(int argc,void** argv){ int rc; rc = $UPDARRAYBYKEY(argv,argv[1],"key1",1,"data1"); if(rc) if($GETSTATUS(argv) != JAM_SCRIPTAPI_NORMAL && $GETSTATUS(argv) != JAM_SCRIPTAPI_NODATA) return -1; return 0; }