IDMCPortLibX Interface

Version: 2.0
Dispatch interface for CPortLibX2 Control

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

This interface includes methods and properties of serial (RS232) communication ports. Typically you open port object, passing port configuration in the parameters of the Open() method, perform data exchange and, finally, close port object. Use IsActive property to determine whether port is ready for communication, Write() method to send data and OnRead event for asynchronous reading.

Members:
Kind Name ID Description
Open 1 Opens COM port
Close 2 Closes COM port
IsActive 3 Determines whether port is opened
Write 4 Writes string to the port
IsVisible 5 Shows or hides terminal
BinaryRead 6 If true, data in OnRead will be array of variants
Handle 7 COM port handle for API calls
Port 8 COM port number
BaudRate 9 BaudRate (number; 300, 9600, ... 256000)
Parity 10 Parity (see cplParity constants)
DataBits 11 DataBits (number, 5..8)
StopBits 12 StopBits (see cplStopBits constants)
Terminator 13 Triggers OnRead event
PortSetupDialog 14 Invokes COM port setup dialog box
SetDTR 15 Set DTR line state
SetRTS 16 Set RTS line state
DSR 17 Returns DSR state
CTS 18 Returns CTS state
AsyncWrite 19 If true, Write returns immediately
IsAsyncCompleted 20 Indicates whether asynchronous operation is completed

Syntax:
function Open(Port, BaudRate, Parity, DataBits, StopBits): 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:
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 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 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.

Syntax:
property BinaryRead: Boolean

Applies to:
CoCPortLib2, CPortLibX2

If this flag is set to True, Data parameter in the IDMCPortLibXEvents interface is an array of bytes, otherwise it is a string.

Syntax:
r/o property Handle: Long

Applies to:
CoCPortLib2, CPortLibX2

For CPortLibX2 and CoCPortLib2 objects this property is a WinAPI handle of the COM port. You can use it as a parameter in other serial API calls.

Syntax:
property Port: Variant

Applies to:
B740X, CoCPortLib2, CPortLibX2, E712X, HP4191X

For CPortLibX2 and CoCPortLib2 objects this property is a string formatted as "COMn", where n is a number of serial port. Notice that you can assign integer numbers (1, 2, ...) to this property.

Syntax:
property BaudRate: Long

Applies to:
CoCPortLib2, CPortLibX2

For CPortLibX2 and CoCPortLib2 objects this property is an integer number that is interpreted as valid RS-232C port baud rate (110, 300, 600, 1200, ... 256000).

Syntax:
property Parity: Long

Applies to:
CoCPortLib2, CPortLibX2

Possible values of this property are listed in the cplParity Enumeration.

Syntax:
property DataBits: Long

Applies to:
CoCPortLib2, CPortLibX2

Syntax:
property StopBits: Long

Applies to:
CoCPortLib2, CPortLibX2

Possible values of this property are listed in the cplStopBits Enumeration.

Syntax:
property Terminator: Variant

Applies to:
CoCPortLib2, CPortLibX2

For CPortLibX2 and CoCPortLib2 objects this property is a string that represents so-called Terminator sequence. If this property is not empty string, the controls accumulate and analyze incoming data stream looking for Terminator substring in the input buffer. IDMCPortLibXEvents.OnRead event triggered only when this sequence is detected. Setting this property (typical values are LF, CR or their combinations) allows you to write very simple and intuitive event handlers.

Notice: In the Binary Mode this property is not used!

Syntax:
function PortSetupDialog: VOID

Applies to:
CoCPortLib2, CPortLibX2

Syntax:
function SetDTR(OnOff): VOID

Applies to:
CoCPortLib2, CPortLibX2

This method allows you to manipulate the state of DTR (Data Terminal Ready) pin of RS-232 connector. This is pin #4 of standard DB9 connector (output). Keep in mind that DTR signal may be used for so-called "hardware handshake" which is not directly supported in CPortLib2. You can however use this method for arbitrary programmatic access to this pin.

Syntax:
function SetRTS(OnOff): VOID

Applies to:
CoCPortLib2, CPortLibX2

This method allows you to manipulate the state of RTS (Request To Send) pin of RS-232 connector. This is pin #7 of standard DB9 connector (output). Keep in mind that RTS signal may be used for so-called "hardware handshake" which is not directly supported in CPortLib2. You can however use this method for arbitrary programmatic access to this pin.

Syntax:
r/o property DSR: Boolean

Applies to:
CoCPortLib2, CPortLibX2

This property returns state of DSR (Data Set Ready) line of RS-232 connector. This is pin #6 of standard DB9 connector (input). Notice that when this signal changed, special IDMCPortLibXEvents.OnDSRChange(OnOff) event fired, where OnOff reflects new value of this property.

If DSR signal is not used for so-called "hardware handshake", you can use it for arbitrary asynchronous boolean input, for example, by shorting DSR and DTR pins through hardware button or switch.

Syntax:
r/o property CTS: Boolean

Applies to:
CoCPortLib2, CPortLibX2

This property returns state of CTS (Clear To Send) line of RS-232 connector. This is pin #8 of standard DB9 connector (input). Notice that when this signal changed, special IDMCPortLibXEvents.OnCTSChange(OnOff) event fired, where OnOff reflects new value of this property.

If CTS signal is not used for so-called "hardware handshake", you can use it for arbitrary asynchronous boolean input, for example, by shorting CTS and RTS pins through hardware button or switch.

Syntax:
property AsyncWrite: Boolean

Applies to:
CoCPortLib2, CPortLibX2

This property allows to activate asynchronous write mode. In this mode, Write method returns immediately and all data to be transmitted are stored in the buffer. When COM port driver finishes data transmission, OnWrite event handler is invoked. Asynchronous write mode especially useful when you have to send large data arrays (such as calibration tables) over slow RS-232 serial interface.

Syntax:
r/o property IsAsyncCompleted: Boolean

Applies to:
CoCPortLib2, CPortLibX2

You can monitor this property to determine when COM port transmission buffer is empty. This may be important if asynchronous write mode was selected (set AsyncWrite=true to enable this feature).