Hitachi

JP1 Version 12　JP1/IT Desktop Management 2 - Asset Console アクセス定義ファイル作成ガイド

$DLLEXEC2（DLL実行関数）

ユーザが作成したユーザ関数を実行します。$DLLEXEC2で実行するユーザ関数とアクセス定義ファイルとの間のデータの受け渡しは、配列変数を使用します。ユーザ関数内で配列変数にアクセスするためには、Asset Consoleが提供するマクロを使用します。

〈このページの構成〉

形式

$DLLEXEC2(DLLオブジェクト,関数名,配列変数名1（,配列変数名2（,…））)

ページの先頭へ

指定する値

ページの先頭へ

使用する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

異常終了（関数の戻り値が正数の場合）

スクリプト中断

次のどちらかを示す

  • 異常終了（関数の戻り値が負数の場合）※

  • 引数の誤り、またはそのほかのエラー
注※

指定したDLLオブジェクトの変数名が、組み込み関数$DLLLOADで求めたDLLオブジェクトではないことを示しています。

ページの先頭へ

注意事項

組み込み関数$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に定義されたマクロの一覧を次に示します。

表5‒2　DLLで使用できるマクロ一覧

マクロ

機能

使用目的

マクロ名

配列の操作

$GETARRAY

配列からのデータ取得

$CLEARARRAY

配列の初期化

$SETARRAY

配列へのデータ設定

$SETARRAYBYKEY

配列へのキー付きデータ設定

$GETARRAYBYKEY

配列からキー付きデータ取得

$GETKEYFROMARRAY

配列から対応するキー取得

$GETARRAYLENGTH

配列の要素数の取得

$GETARRAYNAME

配列名の取得

$UPDARRAY

配列データの更新

$UPDARRAYBYKEY

キー付き配列データの更新

インスタンスの取得

$GETINITAREA

aim_init関数の戻り値の取得

状態の取得

$GETSTATUS

関数の終了状態の詳細を取得

DLL作成時に使用できる各マクロについて説明します。

ページの先頭へ

■$CLEARARRAY（配列初期化マクロ）

指定した配列に格納されている情報をすべて削除して、配列を初期化します。

形式（相当関数形式）
int $CREARARRAY(void** argv,void* array);
引数

  • argv

    スクリプトで指定した配列変数群の先頭アドレス

  • array

    配列変数群の要素の一つ（ユーザ関数の引数）

戻り値

戻り値

内容

0

正常終了

-1

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した、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

エラー※、または指定した位置番号の情報が存在しない

注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※、または指定したキー内配列番号の情報が存在しない

注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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、または指定した配列番号の値が存在しない

注※1

指定した配列要素にキーが付いていない場合、0バイトの文字列が返されます。

注※2

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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

エラー※
注※

詳細なエラー情報は、$GETSTATUS（マクロの終了状態の取得マクロ）で取得できます。

コーディング例

スクリプトで指定した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;
}

ページの先頭へ

Copyright (C) 2019, 2020, Hitachi, Ltd.

Copyright (C) 2019, 2020, Hitachi Solutions, Ltd.

Copyright, patent, trademark, and other intellectual property rights related to the "TMEng.dll" file are owned exclusively by Trend Micro Incorporated.