<< Click to Display Table of Contents >> Navigation: Reference (Scripting) > Docklight Script Commands - The DL Object > Methods > StartLogging |
Creates new log file(s) and starts logging the incoming/outgoing serial data. This corresponds to the Docklight menu Start Communication Logging ...
Return Value
Void
Syntax
DL.StartLogging baseFilePath [, appendData] [, representations] [, format] [, highspeed] [, noHeaders]
The StartLogging method syntax has these parts:
Part |
Description |
baseFilePath |
Required. String containing the directory and base file name for the log file(s). |
appendData |
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. |
representations |
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). |
format |
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: |
highspeed |
Optional Boolean value. False (Default) = not used True = Disable communication window while logging (e.g. for monitoring high-speed communications on a slow PC). |
noHeaders |
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. |
Remarks
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
' Example StartLogging
DL.ClearCommWindows
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
DL.StopLogging
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
Const LOG_REPRESENTATIONS = "AH"
currentLogFileName = ""
DL.StartCommunication
Do
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
Loop
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