IDMDLLHelper Interface

Version: 2.0
Dispatch interface for DMDLLHelper Object

GUID: {673AAF1D-9A0B-11D4-B2A4-FD6847C75367}

This interface includes methods and properties of so-called "DLL wrapper" object used to invoke external DLL procedures from scripts. Since DLLs, unlike ActiveX components, usually have no type information, you need to build special member description file first. You can use DLL Wizard from the Script Editor to make this job faster and more convenient.

Typically you open DMDLLHelper object, providing INI file with type information in the FName parameter of Open() method, perform API calls and, finally, close DMDLLHelper object. Use IsActive property to determine whether DMDLLHelper object is still opened and ready for action.

As of build #420, new DMAppHelper coclass implements this interface to provide access to the DM2003 DOM to any in-process code units that do not have direct pointer to the DMInternalApplication object. You should use DMAppHelper in the same way as above for DMDLLHelper.

Members:
Kind Name ID Description
API 0 Dynamic interface or nil if library not loaded
IsActive 1 True if library is loaded
Open 2 Loads DLL specified by given description file, returns true if OK
Close 3 Unloads DLL, returns true if OK

Syntax:
r/o property API: IDispatch

Applies to:
DMAppHelper, DMDLLHelper

For DMDLLHelper, this property returns dynamically created dispinterface whose methods represent API of the loaded DLL. If no DLL is loaded, null pointer is returned. For DMAppHelper, a reference to DMInternalApplication CoClass is returned. DMAppHelper obtains this reference from a published property of VCL object (via RTTI), while VCL object can be found by window handle using so-called global atom table. Null pointer may be returned if this search was unsuccessful.

Syntax:
r/o property IsActive: Boolean

Applies to:
B740X, CoCPortLib2, CPortLibX2, DMAppHelper, DMClientSocket, DMComPort, DMComTerminal, DMDLLHelper, DMIEEE488Port, E712X, HP4191X

This property indicates whether appropriate component was successfully opened. For example, Open() method prepares hardware port or instrument driver for communication. Typically you open component, perform data exchange (invoke methods) and, finally, close the component.

Syntax:
function Open(FName): Boolean

Applies to:
CoCPortLib2, CPortLibX2, DMAppHelper, DMClientSocket, DMComPort, DMComTerminal, DMDLLHelper, DMIEEE488Port, DMIniFile, DMRegistry

For DMINIFile, Open method opens selected INI file (Name parameter) and fills Values collection with either section names or parameter names. Open() includes some name parsing: section name (if any) should be delimited by * character from file name and by # character for URLs.

For DMRegistry, Name parameter must be full path to the selected registry key. Use RegEdit to copy-and-paste appropriate values.

WARNING: because of security reasons, the functionality of DMRegistry intentionally limited to those operations required by DM2003. In particlar, root key is ALWAYS read-only, some other keys are just unavailable.

DMDLLHelper, DMINIFile and DMRegistry Open() returns True if operation successfull, and False otherwise. For URLs DMINIFile.Open always return True, and INI file always is read-only. As of DMForms build #300, DMDLLHelper also supports URLs.

Currently for DMAppHelper, Open member does nothing and does not use parameter. It just returns true if API reference is valid, while actually connects to DM2003 at the control creation moment.


For DMIEEE488Port, DMClientSocket and RS-232 port controls Settings parameters of the Open() method determine port settings. It doesn't return any result. Notice that CPortLibX2, CoCPortLib2, DMClientSocket, DMComPort and DMComTerminal support "binary" mode of communication.

Examples:

' DMINIFile:
if DMINIFile.Open("C:\MyFile.ini", false) then
if DMINIFile.Open("http://server/path/file.txt#Columns", true) then

' DMRegistry:
const Key="HKEY_CURRENT_USER\Software\RRR\DM2003\Data Master" 
if DMRegistry.Open(Key, true) then 


' DMComPort, DMComTerminal:
' open COM4, 9600bps, no parity, 8 data bits, 1 stop bit, 
' character mode, asynchronous write mode
call DMComPort.Open("4,9600,0,8,0,0,-1") ' full string
call DMComPort.Open("4")                 ' short string

' or use array of parameters
dim Settings(5)  ' Settings(6) - for use Async Write mode
Settings(0)=4    ' COM port number 1, 2, ...  
Settings(1)=9600 ' baud rate (110, 300, 600, ... 256000)
Settings(2)=0    ' parity: 0=None, 1=Odd, 2=Even, 3=Mark, 4=Space
Settings(3)=8    ' data bits: 5..8
Settings(4)=0    ' stop bits: 0=OneStopBit, 1=One5StopBits, 2=TwoStopBits
Settings(5)=0    ' mode: -1=binary, 0=character (default)
'Settings(6)=-1    write mode: -1=asynchronous, 0=synchronous (default)
call DMComPort.Open(Settings)

' DMIEEE488Port:
call DMIEEE488Port.Open("IEEECTRL") ' open command file
call DMIEEE488Port.Open(True)       ' open command file
call DMIEEE488Port.Open("IEEEDATA") ' open data file
call DMIEEE488Port.Open(False)      ' open data file

' DMDLLHelper:
if DMDLLHelper.Open("C:\path\APIdescription.ini") then
b=DMDLLHelper.Open("http://datamaster2003.com/samples/dll/dllhelpertest.ini")

' CPortLibX2, CoCPortLib2:
ComPort1.Open 1, 9600, 0, 8, 0

See also:
DMINIFile, DMRegistry, DMComTerminal, DMComPort, DMIEEE488Port test pages.

Syntax:
function Close: Boolean

Applies to:
CoCPortLib2, CPortLibX2, DMAppHelper, DMApplication, DMClientSocket, DMComPort, DMComTerminal, DMDLLHelper, DMDocument, DMIEEE488Port, DMInternalApplication

For DMDocument, this procedure closes document window. It is similar to Window|Close menu command.

For DMIEEE488Port, DMClientSocket, DMComPort and DMComTerminal, Close method closes the appropriate communication port.

DMDLLHelper.Close unloads DLL so that all subsequent API calls become impossible. DMAppHelper.Close also clears internal reference to DM2003 DOM. It is recommended to close these objects after use.

DMApplication.Close should be invoked to terminate DM2003. Unlike executing ExitAction, it does not display COM server warning for external (out of process) servers. For example, you may place following code in the HTML page loaded into the separate instance of MSIE browser:

Example:

sub Btn_onclick
dim app
  set app=CreateObject("DM.DMApplication")
  ' do something useful...
    . . . . .
  ' wrong - does not avoid COM warning message:
  'app.ExecuteCommand "ExitAction"
  ' right - nothing displayed if no unsaved data:
  app.Close
  set app=Nothing
end sub