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.
|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|
|function Open(Port, BaudRate, Parity, DataBits, StopBits): VOID|
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.
' 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
|function Close: VOID|
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:
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
|property IsActive: Boolean|
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.
|function Write(Data): VOID|
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)
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.
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
|property IsVisible: Boolean|
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.
|property BinaryRead: Boolean|
If this flag is set to True, Data parameter in the IDMCPortLibXEvents interface is an array of bytes, otherwise it is a string.
|r/o property Handle: Long|
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.
|property Port: Variant|
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.
|property BaudRate: Long|
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).
|property Parity: Long|
Possible values of this property are listed in the cplParity Enumeration.
|property StopBits: Long|
Possible values of this property are listed in the cplStopBits Enumeration.
|property Terminator: Variant|
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!
|function SetDTR(OnOff): VOID|
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.
|function SetRTS(OnOff): VOID|
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.
|r/o property DSR: Boolean|
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.
|r/o property CTS: Boolean|
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.
|property AsyncWrite: Boolean|
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.