$DLLEXEC2 (execute DLL)

Syntax

$DLLEXEC2(DLL-object,function-name,array-name-1(,array-name-2(,...)))

To Page Top

Values

• DLL-object

  Specifies the variable name of the DLL object that was acquired by $DLLLOAD.

• function-name

  Specifies the name of the function to be executed, as either a constant or a variable. A constant must be enclosed in single quotation marks ('').

• array-name

  Specifies the name of the array variable containing the information to be passed to the function, or the name of the array variable for acquiring the execution result of the function.

To Page Top

DLL interface to be used

The following shows the format of the function that is called by $DLLEXEC2:

int function-name(int argc       //number of array variables
                              //specified in the script
            ,void**  argv     //start address of the group of array
                              // variables specified in the script
           )

The array variables specified in the script are stored sequentially (from left to right) beginning at array 0 of argv. Therefore, the array name 1 and array name 2 are processed internally as argv[0] and argv[1], respectively, by the function.

If the function returns a negative value, the function executes the aim_getmessage function (provided in the same DLL by the user). If a message has been specified, the function writes that message in the Asset Console log, and then cancels the script execution.

To Page Top

Status

The following table lists and describes the possible statuses:

To Page Top

Note

The user must have previously provided the DLL containing the user functions that are called by the $DLLEXEC2 embedded function.

To Page Top

Example

This example loads sample.dll and executes the summing function FunctionSum. It sets arguments 10, 20, and 30 in the loaded sample.dll, executes FunctionSum, and then outputs the result.

[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)

To Page Top

Creating a user function to be executed by $DLLEXEC2

If the user function to be executed by $DLLEXEC2 does not need to transfer data with the script, you can create a DLL with the general procedure.

In some cases, it might be desirable to let user function receive information from the script, or to set the processing result of the user function in an array of the script. To do this, you must use a special function provided by Asset Console to access the script's array variables. Asset Console provides a function for accessing such array variables as a macro.

The macros are defined in the header file for C and C++ language jamScriptAPI.h. By including this header file, you can manipulate arrays with the same interface you use for the functions in the access definition file.

Note that from $DLLEXEC2 you can execute only those functions that use array manipulation macros that are included in the DLL.

jamScriptAPI.h is stored in the following folder:

Asset-Console-installation-folder\sdk\include

The following table lists and describes the macros defined in jamScriptAPI.h:

The following subsections describe each macro available during DLL creation.

To Page Top

■ $CLEARARRAY (initialize array)

$CLEARARRAY deletes all information stored in the specified array and initializes the array.

Format (equivalent function format)

int $CREARARRAY(void** argv,void* array);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the group of array variables (argument of the user function).

Return values

Coding example

This example initializes array 1 specified in the script:

int DllFunc8(int argc,void** argv){
  int rc;
  rc = $CLEARARRAY(argv,argv[0]);
  if(rc)return-1;
  return 0;
}

To Page Top

■ $GETARRAY (get value of array data)

$GETARRAY acquires information from the array at the specified location.

Syntax

char* $GETARRAY(void** argv,void* array,int pos);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the group of array variables (argument of the user function).

• pos

  Specifies the position in the array from which information is to be acquired (begins at 1).

Return values

Coding example

This example acquires information 1 in array 1 specified in the script:

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;
}

To Page Top

■ $GETARRAYBYKEY (get value from array with key)

$GETARRAYBYKEY uses a specified key to acquire information from an array created using the $SETARRAYBYKEY embedded function in the script, or from an array created using the $SETARRAYBYKEY macro in the user function. If there is more than one element with the same key, specify the array number in the key to identify the location of the applicable element.

Syntax

char* $GETARRAYBYKEY(void** argv,void* array,char* key,int pos);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the group of array variables (argument of the user function).

• key

  Specifies the key.

• pos

  Specifies the array number in the key (begins at 1).

Return values

Coding example

From array 1 specified in the script, this example acquires information about array 1 in the key stored by the key1 key:

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;
}

To Page Top

■ $GETARRAYLENGTH (get number of array elements)

$GETARRAYLENGTH acquires the number of elements in the specified array.

Syntax

int $GETARRAYLENGTH(void** argv,void* array);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the group of array variables (argument of the user function).

Return values

Coding example

This example acquires the number of elements in array 1 specified in the script:

int DllFunc10(void* obj,void* functbl,int argc,void** argv){
  int len;
  len = $GETARRAYLENGTH(argv,argv[0]);
  if (len<0) return -1;
  return 0;
}

To Page Top

■ $GETARRAYNAME (get name of array)

$GETARRAYNAME acquires the array name of a specified array.

Syntax

char* $GETARRAYNAME(void** argv,void* array);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the group of array variables (argument of the user function).

Return values

Coding example

This example acquires the array name of array 1 specified in the script:

int DllFunc9(int argc,void** argv){
  char* name;
  name = $GETARRAYNAME(argv,argv[0]);
  if(!name) return -1;
  return 0;
}

To Page Top

■ $GETINITAREA (get return value of aim_init function)

$GETINITAREA acquires an instance, which is the return value of the aim_init function.

Syntax

void * $GETINITAREA(void** argv);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

Return value

Return value of the aim_init function (instance)

Coding example

This example acquires the return value of the aim_init function:

int DllFunc(int argc, void** argv){
  USER_HANDLE*  obj;
  obj = $GETINITAREA(argv);
  return 0;
}

To Page Top

■ $GETKEYFROMARRAY (read corresponding key from array)

$GETKEYFROMARRAY acquires the key information having the specified array number from the information stored in the array with the key.

Syntax

char* $GETKEYFROMARRAY(void** argv,void* array,int pos);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the group of array variables (argument of the user function).

• pos

  Array number of the array element for which information is to be acquired (begins at 1).

Return values

Coding example

This example acquires key information stored in array element 1 of array 3 specified in the script:

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;
}

To Page Top

■ $GETSTATUS (get details of macro termination status)

$GETSTATUS acquires the termination status of the processing.

Syntax

int $GETSTATUS(void** argv);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

Return value

Return value	Description
JAM_SCRIPTAPI_NORMAL	Normal end
JAM_SCRIPTAPI_DUPLICATE	Duplicate key value
JAM_SCRIPTAPI_NODATA	No corresponding array data
JAM_SCRIPTAPI_INSUFFICIENTMEMORY	Insufficient memory for processing
JAM_SCRIPTAPI_ILLEGAL	Illegal call interface
JAM_SCRIPTAPI_ERROR	Other internal error

Coding example

See the coding example in $GETARRAY (get value of array data).

To Page Top

■ $SETARRAY (set value to array)

$SETARRAY adds information to an array.

Syntax

int $SETARRAY(void** argv,void* array,char* value);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the array variable group (argument of the user function to which information is to be added).

• value

  Specifies the information to be added (character string).

Return values

Coding example

This example adds an array element using information data1 to array 2 specified in the script:

int DllFunc1(int argc, void** argv){
  int rc;
  rc = $SETARRAY(argv,argv[1],"data1");
  if(rc) return -1;
  return 0;
}

To Page Top

■ $SETARRAYBYKEY (set value to array with key)

$SETARRAYBYKEY adds information to an array with a key.

Syntax

int $SETARRAYBYKEY(void** argv,void* array,char* key,char* value);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the array variable group (argument of the user function to which information is to be added).

• key

  Specifies the key.

• value

  Specifies the information to be added (character string).

Return values

Coding example

This example adds an array element using the key value key1 and the information data1 to array 2 specified in the script:

int DllFunc2(int argc,void** argv){
  int rc;
  rc = $SETARRAYBYKEY(argv,argv[1],"key1","data1");
  if(rc) return -1;
  return 0;
}

To Page Top

■ $UPDARRAY (update array data)

$UPDARRAY updates the value of an array element of an array variable. The array element is specified by its array number.

Syntax

int $UPDARRAY(void** argv,void* array,int pos,char* value);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the array variable group (argument of the user function whose array element is to be updated).

• pos

  Specifies the array number of the array element whose Array information is to be updated (begins at 1).

• value

  Specifies the new data to be used (character string).

Return values

Coding example

This example updates the value of array element 2 of array 2 specified in the script to 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;
}

To Page Top

■ $UPDARRAYBYKEY (update value of array with key)

$UPDARRAYBYKEY updates the value of an array element of an array variable. The array element is expressed as a key and array number in the key.

Syntax

int $UPDARRAYBYKEY(void ** argv,void* array,char* key,int pos,char* value);

Arguments

• argv

  Specifies the start address of the group of array variables that were specified in the script.

• array

  Specifies one of the elements of the array variable group (argument of the user function whose array element is to be updated).

• key

  Specifies the key.

• pos

  Specifies the array number in the key (begins at 1).

• value

  Specifies the new data to be used (character string).

Return values

Coding example

This example updates the value of array element 1 stored by the key key1 in array 2 specified in the script to 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;
}

To Page Top