StartLogging

<< 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 logging 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:
False = plain text (.txt)
True = HTML (.htm)

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

 

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

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