9.6.1 CallDll (call a DLL file)

Purpose

Calls a dynamic-link library (DLL) file.

Syntax

CallDll(DllFileName, FunctionName, Param1, Param2, ...)

Arguments

DllFileName

Specify the DLL file name as a character string or as a variable that stores this value.

FunctionName

Specify the external function to invoke. Write a character string or a variable that stores this value.

Param1 to Param32

Specify each of the function parameters as a character string or as a variable that stores this value.

In JP1/Script 06-00 and later versions, you can specify an array variable that stores all the required parameters.

Description

The CallDll command loads the specified DLL and calls an external function. The command returns True on successful execution, or False if an error occurs.

Use the following interface for the external function. The external references must be declared in the EXPORTS section of the module definition file (.DEF).

Declaration

BOOL  WINAPI  MyFunc(HWND hParent, int argc, char * argv[], int * rtnc, char * * rtnv[]);

Arguments

HWND hParent;

Handle of the parent window
int argc;

Number of parameters to be passed from the script
char * argv[];

Array that stores the parameters to be passed from the script
int * rtnc;

Pointer to the number of strings to return to the script.
char * * rtnv[];

Array that stores the number of strings to return to the script.

Return values

The return value of the MyFunc external function is stored in the _DLL_RTN_ reserved variable. When True is set in _DLL_RTN_, you can use the _RTNxx_ reserved variable in your script to reference the array holding the strings to be returned to the script, stored in the rtnv argument. Here, xx is a sequential number starting from 00, up to the number stored in the rtnc argument.

When False is set in _DLL_RTN_, the _RTNxx_ reserved variable is undefined.

To enable the returned string and string array to be referenced after the function completes, do not store these values in a local buffer within the scope of the function.

Note

The loaded DLL file will be unloaded when the command terminates. If you do not want to unload the DLL file, set 1 in the following registry key. The loaded DLL file will not be unloaded until execution of the script terminates.

Registry key

HKEY_LOCAL_MACHINE\SOFTWARE\HITACHI\JP1/Script\SPTX

Value name

CallDllUnloadMode

Value datatype

REG_DWORD

Value

0: Unload DLL files.

1: Do not unload DLL files.

When the setting takes effect

The setting takes effect the next time the script file is executed.

Important note

Note the following when you specify not to unload DLL files:

The DllMain function, which is a DLL entry point function, is called from the Windows system and executed when a DLL file is loaded. Therefore, if you execute the CallDll command multiple times with the same DLL file specified, the DllMain function is executed during the first execution of the command, which loads the DLL file. The DllMain function is not executed at the second or subsequent executions of the command because no DLL file is loaded.
The external variables used in the DLL are initialized when the DLL file is loaded. Therefore, if you execute the CallDll command multiple times with the same DLL file specified, the external variables are initialized during the first execution of the command, which loads the DLL file. The external variables are not initialized at the second or subsequent executions of the command because the DLL file is not loaded.
To specify DLL files with the same name and different entities, use absolute paths. If you use relative paths to specify such DLL files, the DLL files will not be loaded even if you specify the path to the executable folder in the SetPath command. This is because the Windows system identifies these DLL files as the same file.
As far as possible, use a DLL file that contains a group of external functions that will be called by the CallDll command. If you use the CallDll command with different DLL files specified, many DLL files will be loaded during execution of the script execution process. As a result, memory might be insufficient.

Example

' Function part of TEST.DLL(Favorite.c)
#include "windows.h"
 
#define  FAV_SPORT1 "SKI"
#define  FAV_SPORT2 "BASKETBALL"
#define  FAV_FOOD1  "STEAK"
#define  FAV_FOOD2  "PASTA"
char *  g_ret[2];
 
BOOL  WINAPI  GetFavorite(HWND hParent, int argc, char * argv[], int * rtnc, char ** rtnv[])
{
  if(lstrcmp(argv[0], "SPORT") == 0)
  {
    g_ret[0] = FAV_SPORT1;
    g_ret[1] = FAV_SPORT2;
  }
  else if(lstrcmp(argv[0], "FOOD") == 0)
  {
    g_ret[0] = FAV_FOOD1 ;
    g_ret[1] = FAV_FOOD2;
  }
 
  *rtnc = 2;
  *rtnv = g_ret;
 
  return(TRUE);
}
 
' Processing(abc.SPT) at the script side
Dim Quest
Quest = "SPORT"
CallDll(_BIN_+"TEST.DLL", "GetFavorite", Quest)
Dim Msg
Msg = "My favorite" +Quest+" are "+_RTN00_+" and "+_RTN01_+"."
MessageBox(Msg, OK, , Information)
Exit(0)

JP1/Script version

Supported from JP1/Script 01-00.

To Page Top