IDMIOPort Interface

Version: 2.1
Dispatch interface for TCP/IP and RS232

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

This interface includes methods and properties of the communication ports. Typically you open port object, passing port configuration in the Settings parameter of the Open() method, perform data exchange and, finally, close port object. Use IsActive property to determine whether port is ready for communication, Read and Write methods to send and receive data.

Members:
Kind Name ID Description
Open 101 Opens communication port
Close 102 Closes communication port
Read 103 Reads string from the communication port
Write 104 Writes string to the communication port
IsActive 105 Changes port active (opened) state
IsVisible 106 Changes port terminal visibility

Syntax:
function Open(Settings): VOID

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: VOID

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

Syntax:
function Read: Variant

Applies to:
DMClientSocket, DMComPort, DMComTerminal, DMIEEE488Port

For DMComPort, DMComTerminal and DMClientSocket this method not supported since read operations for RS232 and TCP/IP are essentially asynchronous. Use OnRead event handler to obtain data from these port controls.

For DMIEEE488Port Read method returns data from the appropriate port or empty string if port is not open.

Syntax:
function Write(Data): VOID

Applies to:
CoCPortLib2, CPortLibX2, DMClientSocket, DMComPort, DMComTerminal, DMIEEE488Port

Note: for DMComPort and DMComTerminal objects, Write method fires OnError event if port is not open! Data parameter may be either string or array of bytes. The latter mode ("binary") allows you to transmit arbitrary data, including null (0x00) character.

For all serial communication controls, Write method returns immediately if asynchronous write mode was selected. Otherwise, it will wait untill COM port transmission buffer will empty.

Examples:

dim Arr(3), Str
Arr(0)=65
Arr(1)=84
Arr(2)=13
Arr(3)=10
Str="AT" & vbCrLf

call DMComPort.Write(Arr) ' binary mode write
call DMComPort.Write(Str) ' character mode write

Syntax:
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:
property IsVisible: Boolean

Applies to:
CoCPortLib2, CPortLibX2, DMAxis, DMClientSocket, DMComboBox, DMComPort, DMComTerminal, DMDigitizer, DMExpressionComboBox, DMFloatEdit, DMIEEE488Port, DMLabel, DMListBox, DMSerie, DMSpinEdit

IsVisible property determines whether appropriate object is visible on the screen. Note that for ActiveX controls embedded in the HTML page, you can also change Object.style.visibility property. Some controls like DMClientSocket, DMIEEE488Port and DMComPort are invisible by design and don't implement this property.