SetChannelSettings

<< Click to Display Table of Contents >>

Navigation:  Reference (Scripting) > Docklight Script Commands - The DL Object > Methods (Advanced) >

SetChannelSettings

Change the current communication channel settings: provide a new COM port number or TCP/IP address, or change the serial port settings (baud rate, parity settings, ...).

 

Serial port settings can be changed on-the-fly, while the communication channel is open. For other changes, e.g. the COM port number itself, StopCommunication must be called before using SetChannelSettings.

 

NOTE:

 

Return Value

 

Boolean

 

Syntax

 

result = DL.SetChannelSettings( newSettings [, channelNo] [, dontTest])

 

The SetChannelSettings method syntax has these parts:

 

Part

Description

newSettings

Required. String with the new communication channel and/or the serial settings. See below for detailed specification

channelNo

Optional. Integer value that specifies the communication channel if Communication Mode: Monitoring is used. Default value is 1 (Channel 1).

dontTest

Optional. Boolean value. If dontTest is set to True, SetChannelSettings does not open and close the communication channel for testing purposes. See the "Remarks" section below. Default value is False (channel is tested to determine return value).

 

The newSettings argument accepts the following values:

 

Value

Description

"COMxxx"

Select new serial communication port, e.g. "COM7"

"RemoteHost:RemotePort"

Make this channel a TCP client and connect to the specified IP address and TCP port number, e.g. "192.0.0.1:3001" (see Projects Settings)

"SERVER:LocalPort"

Make this channel a TCP server, accepting connections on the specified TCP port, e.g. "SERVER:3001" (see Projects Settings)

"UDP:RemoteHost:Port"

Makes this channel a UDP peer, transmitting data to RemoteHost:Port and listening to the local Port (see Projects Settings)

"USBHID:vendorId:productId"

USB HID input / output report access (see Projects Settings).

"PIPE:myNamedPipe"

Client connection to a Named Pipe with read/write access (see Projects Settings).

"COMxxx:BaudRate,Parity,
DataBits,StopBits"

Select new serial port and serial communication settings

Parity can be NONE, EVEN, ODD, MARK, SPACE.

Example: "COM18:9600,EVEN,8,1"

"BaudRat,Parity,DataBits,
StopBits"

Changing the serial settings without knowing/changing the current serial port. Example: "38400,NONE,8,1"

"BaudRat,Parity,DataBits,
StopBits,FlowControl,ParityErrorChar"

Extended syntax to additionally change the hardware flow control options:

FlowControl can be OFF, RTSCTS, XONXOFF, RTSSEND

ParityErrorChar: The decimal ASCII code for the Parity Error Character (see Projects Settings). Default value is 63.

Example: "9600,NONE,8,2,RTSCTS,35"

">"

Find the next serial COM port available on this PC. If the currently selected port is COM1, SetChannelSettings will start searching at COM2.

 

Remarks

 

For most applications it is not necessary to use SetChannelSettings or its companion, GetChannelSettings. Communication parameters can be chosen  in the Project Settings dialog, and stored in the Docklight project file (see Saving and Loading Your Project Data and the Open Project method).

 

The SetChannelSettings method is intended for advanced Docklight Scripting applications, where control of the communication channel settings during script runtime is required. It allows you to create scripts that access different COM ports (see example below), or walk through a list of IP addresses.

 

SetChannelSettings method will produce an error, if an illegal value is passed with newSettings.

 

If the newSettings argument is valid (and the dontTest flag is not set), the communication channel will be opened and closed again immediately for a test.

 

If dontTest is True, SetChannelSettings will not open/close the channel for testing, and return always True. This is useful in networking applications, where additional connect/disconnect attempts might confuse the other host/device. Problems have been experienced for example with Telnet server applications.

 

The return value of SetChannelSettings is True, if the channel could be successfully opened (or the new settings are ok and dontTest is true).

The return value is False, if the settings are invalid or an error occurred while trying to access the port (e.g. the COM port already in use, or the Firewall denied the TCP/IP access).

 

NOTE: Modifying the FlowControl parameter when Project Settings: Flow Control is other than "Off" can result in undefined behavior.

 

See also GetChannelSettings and GetChannelStatus.

 

Example

 

' Example SetChannelSettings / GetChannelSettings

' (requires Docklight in Send/Receive mode)

 

DL.ClearCommWindows

 

DL.AddComment "Searching for first COM port available on this PC..."

portAvailable = DL.SetChannelSettings("COM1:9600,NONE,8,1")

While Not portAvailable

   oldPort = DL.GetChannelSettings()

  ' try next COM port

   portAvailable = DL.SetChannelSettings(">")

   newPort = DL.GetChannelSettings()

  ' tried out already all COM ports on this PC?

  If (oldPort = newPort) Then

       DL.AddComment "No COM port available"

       DL.Quit

  End If

Wend

DL.AddComment "Using COM port " & DL.GetChannelSettings()

 

' Try a few different baud rates

baudRatesStr = "9600,14400,57600,115200"

baudRatesArray = Split(baudRatesStr, ",")

For i = 0 To UBound(baudRatesArray)

  ' Tweak the serial port settings

   DL.SetChannelSettings(baudRatesArray(i) + ",NONE,8,1")

   DL.AddComment

   DL.AddComment

   DL.AddComment "Testing with settings " & DL.GetChannelSettings()

  ' Send a modem test command and allow some waiting time for the answer

   DL.StartCommunication

   DL.SendSequence "", "ATI3" + Chr(13) + Chr(10)

   DL.Pause 200

   DL.StopCommunication

Next

 

After running the script on a computer with a built-in modem on COM3, the Docklight communication window could look like this:

 

Searching for first COM port available on this PC...

Using COM port COM3:9600,NONE,8,1

 

 

Testing with settings COM3:9600,NONE,8,1

 

28.01.2008 16:28:36.26 [TX] - ATI3<CR><LF>

 

28.01.2008 16:28:36.26 [RX] - ATI3<CR>

<CR><LF>

Agere SoftModem Version 2.1.46<CR><LF>

<CR><LF>

OK<CR><LF>

 

 

Testing with settings COM3:14400,NONE,8,1

 

28.01.2008 16:28:37.46 [TX] - ATI3<CR><LF>

 

28.01.2008 16:28:37.46 [RX] - ATI3<CR>

<CR><LF>

Agere SoftModem Version 2.1.46<CR><LF>

<CR><LF>

OK<CR><LF>

 

 

Testing with settings COM3:57600,NONE,8,1

 

28.01.2008 16:28:38.60 [TX] - ATI3<CR><LF>

 

28.01.2008 16:28:38.60 [RX] - ATI3<CR>

<CR><LF>

Agere SoftModem Version 2.1.46<CR><LF>

<CR><LF>

OK<CR><LF>

 

 

Testing with settings COM3:115200,NONE,8,1

 

28.01.2008 16:28:39.73 [TX] - ATI3<CR><LF>

 

28.01.2008 16:28:39.73 [RX] - ATI3<CR>

<CR><LF>

Agere SoftModem Version 2.1.46<CR><LF>

<CR><LF>

OK<CR><LF>