LoadDLL

(Engine-Level Function)

Description:	Loads a Microsoft Windows™ dynamic link library. 64-bit VTScada can load only 64-bit DLLs. 32-bit VTScada can load only 32-bit DLLs. VTScada Internet Clients (VICs) can load only 32-bit DLLs regardless of whether the VTScada server is 32-bit or 64-bit.
Returns:	DLL handle, numeric error code, or Invalid. See comments
Usage:	Steady State only.
Function Groups:	Compilation and On-Line Modifications, DLL, Software and Hardware
Related to:	DLL
Format:	LoadDLL(FileName[, VICRemoted])
Parameters:

FileName

Required. Any text expression for the file name of the DLL to load. If the path is not specified, the standard Windows search pattern for DLLs will be used.

Windows applications that load DLL's without using a fully qualified pathname are vulnerable to DLL hijacking where an attacker can place a malicious copy of the DLL in the search path. Take care to specify the path in all cases.

VICRemoted

(Optional). A parameter that indicates whether the handle returned by LoadDLL will be remoted to the VIC.
If VICRemoted is a valid, non-zero, positive integer, and the LoadDLL function is being executed in a module instance that is within a VIC session, then all DLL calls using the handle that LoadDLL returns will be remoted to the VIC.
Whether the LoadDLL is in a VIC session is determined by the call tree from the module instance running the LoadDLL call. The root of the call tree must be an instance of BrowserClient. In practical terms, this means that you cannot expect session-aware DLL calls to function if you explicitly launch a module with a caller other than a module instance within the VIC session tree.
Defaults to 0 if not otherwise specified.

Comments:

Your DLL must return an object as a buffer in order for VTScada to be able to read it.

The return value is either the Windows™ handle of the new DLL (ValueType == 38), or on failure, the least significant 16-bits of operating system error code (ValueType < 3).
There is no dynamic download of a DLL to the VIC. DLLs must be manually installed on the VIC in either the system program folder (e.g. \Windows\System 32), or in a folder that is on the executable search path (the PATH environment variable).
LoadDLL is a steady-state statement. If it stops, all VALUEs holding a copy of the DLLHandle returned from the LoadDLL statement will be invalidated, and if there are no other LoadDLLs running for the same DLL, the DLL will be unloaded. (LoadDLL is not an expensive operation, but it is good programming not to do this very often.)

Note: LoadDLL will block the calling interpreter thread until the DLL loaded has completed on the VIC. This means that nothing else will execute on the VIC session thread until the DLL load is complete. This has the advantage (from the programmer's perspective) that the DLL handle returned is immediately ready for use. LoadDLL will return Invalid if there is a problem with the parameters, an integer error code if it cannot load the DLL, or a DLLHandle (ValueType ==38) if the load was successful. On failure, the return value will be the least significant 16-bits of operating system error code (ValueType < 3).

DLL calls do not need to consume the return value, or have no return value should be written as such (i.e. explicitly specify a return type of zero to indicate that there is no return value, or that the return value is irrelevant. If you specify other than zero for the return type, the DLL call will block the calling interpret thread until the VIC has run the DLL call and returned the value. This means that scripts that rely on synchronous DLL calls will still work, even with the DLL remoted, however, they will slow down. If you specify a return value type of zero, a remoted DLL call is dispatched to the VIC asynchronously (i.e. your interpreter thread will not block). If, for example, you have a sequence of DLL calls that will execute asynchronously, followed by one that is synchronous (because you want the return value), the calling interpreter thread will block only on the synchronous call. This may take a little longer because the order of the DLL calls is preserved on the VIC, and all the asynchronous ones will have to complete execution before the synchronous one can be executed. This is much quicker than using all synchronous calls, because the asynchronous ones are batched together and require no reply (other than a batch acknowledgment from the VIC), reducing comms latency.
DLL handles should not be declared as shared if they are going to be remoted. Shared DLLs will only be created once, and so will only operate on the server OR client, depending upon which one started them first.