<< Click to Display Table of Contents >>

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


Creates new log file(s) and starts logging the incoming/outgoing serial data. This corresponds to the Docklight menu logging Start Communication Logging ...


Return Value






DL.StartLogging baseFilePath [, appendData] [, representations] [, format] [, highspeed] [, noHeaders]


The StartLogging method syntax has these parts:





Required. String containing the directory and base file name for the log file(s).


Optional Boolean value.

True (Default) = Append the new data to existing log file(s).

False = Overwrite existing log file(s). Previously saved logging data will be lost.


Optional String to choose the log file representations.

"A" (ASCII), "H" (HEX), "D" (Decimal) and/or "B" (Binary).

Default value is "AHDB"

(create all four representations ASCII, HEX, Decimal, Binary).


Optional Integer value.

0 (Default) = create plain text files (.txt)

1 = create HTML files for web browsers (.htm)

2 = create RTF Rich Text Format files (.rtf)


NOTE: For compatibility to V2.2. and earlier, it is also possible to use:
False = plain text (.txt)
True = HTML (.htm)


Optional Boolean value.

False (Default) = not used

True = Disable communication window while logging

(e.g. for monitoring high-speed communications on a slow PC).


Optional Boolean value.

False (Default) = create a standard header "Docklight Log File started..." after opening the file. Create a footer "Docklight Log File stopped" when closing the file.

True = Do not create any additional header or footer information.




See also logging and analyzing a test and the Create Log Files(s) Dialog for more information on the StartLogging functionality and arguments described above.


If baseFilePath is an empty string, a file dialog will be displayed to choose the log file path and base file name.


If StartLogging is called while another log file is still open from a previous StartLogging call, the file is closed and the new file is created / opened. This allows changing the log file name without losing any data.


The noHeaders flag is particularly useful when you are creating log data without time stamps. You can then easily compare the result to previous test runs using an  file compare tool.





' Example StartLogging



DL.StartLogging "C:\DocklightLogging"

' - opens four log files:

'  'C:\DocklightLogging_asc.txt'

'  'C:\DocklightLogging_hex.txt'

'  'C:\DocklightLogging_dec.txt'

'  'C:\DocklightLogging_bin.txt'

' Wait for 5 seconds

DL.Pause 5000

' Close the four log files



Example 2


This is a more advanced example which demonstrates how to include a date/time stamp in the log file name and start a new log file every hour


' Example 'One Log File per Hour'


' This is the base path and location where the log file(s) will be stored

Const BASE_FILE_PATH = "logfile_"

' Create ASCII and HEX log files



currentLogFileName = ""



   newLogFileName = getFileName()

  ' Time for starting a new file?

  If newLogFileName <> currentLogFileName Then

       DL.StartLogging newLogFileName, True, LOG_REPRESENTATIONS

    currentLogFileName  = newLogFileName

  End If

   DL.Pause 1 ' reduce CPU load



Function getFileName()

   dt = Now

  ' Compose a file name.

  ' The Right() functions ensure that all months, days,

   ' hours are printed with two decimals

   getFileName = BASE_FILE_PATH & Year(dt) & "_" & Right("0" & Month(dt), 2) & "_" & Right("0" & Day(dt), 2) & "_" & Right("0" & Hour(dt), 2) & "H"

End Function