Filtering, Modifying, and Reporting with Scripts

DXKeeper Online Help Contents

A Script is a text file containing lines of commands that

• filter the Log Page Display using structured query language (SQL) expressions

• sort the Log Page Display using SQL expressions

• generate log reports

• generate award progress reports

• modify QSOs in the Log Page Display

Any characters between // and // on a line are ignored, and thus can be used as explanatory comments.

You can run a script by

• clicking the Script button in the Filter panel on the Main window's Log QSOs tab; if the Script button is not visible in this panel, click the ~ button at the left end of the panel and the Script button will become visible.

• clicking the Script button on the Main window's Check Progress tab

• clicking the Run button in the Advanced Sorts, Filters, and Modifiers window

In each case, you will be prompted to select a file containing the script you wish to run;script filename extensions can be either .txt or .scp. When you direct DXKeeper to run a script it determines whether that script will modify your log; if so, it offers to create a backup copy of your log (highly recommended!). DXKeeper then executes each of the script's commands in sequence, and records each executed command in a script log file with an indication as to its success or failure.

The script log file is created in the folder in which the script file resides; its filename is constructing by appending _Log_YYYY_MMM_DD to the script log's filename, where YYYY is the current year, MMM is the current month, and DD is the current day, and its filename extension is .log .

Script Commands

The Filter command specifies a structured query language (SQL) expression that is used to filter the Log Page Display. The number of QSOs present in the Log Page Display after executing the Filter command is recorded in the script log file. This Filter command, for example, 

Filter QSO_Begin < #1/1/1979# and call like '*KB6*'

selects all QSOs with Baker and Howland Islands prior to January 1, 1979.

Ordinarily, DXKeeper remembers the Log Page Display Filter in effect before you initiated script execution, and restores this filter after script execution has completed. If the selected script contains the command Retain Filter, however, DXKeeper does not restore the original Log Page Display Filter; the Log Page Display Filter will be established by the last Filter command executed by the script. This allows script files to be used purely to filter the Log Page Display.

The Sort command specifies an expression which is used to sort the Log Page Display. The expression specifies the items by which the log is to be sorted, with each item's ADIF field name separated by comma's. They keyword DESC is appended if an item is to be placed in descending rather than ascending order. Thus

    Sort Band DESC, Call

will sort the Log Page Display by band in descending order, and then by callsign in ascending order. Executing a script containing a Sort command will clear the Sort panel on the Main window's Log QSOs tab.

The Report command directs the generation of a log or progress report into a specified filename. Its generic format is

         Report Kind ReportFilename

Kind can be one of the following values

ReportFilename supports the following substitution commands:

For example, the commands

        Filter Band='6m'
    Report Grids C:\Program Files\DXKeeper\Reports\<operator>6M grids.txt

will produce a 6 meter Maidenhead Gridsquare progress report in the file 

AA6YQ 6M grids.txt  

in the folder 

C:\Program Files\DXKeeper\Reports.

The log report's sort order and layout are those of the Log Page Display with one exception: if the Log Page Display includes the country code, the report appends the full DXCC entity name to the country code. You can create a layout optimized for this report and save it in a file for later recall, as described below. 

The LoadLayout command specifies a filename containing a Log Page Display layout file, which is loaded and applied. This allows a layout optimized for a particular report to be instituted, the report generated, and the normal Log Page Display layout restored:

        LoadLayout C:\Program Files\DXKeeper\Configurations\GridReport.txt
    Filter Band='6m'
    Report Grids C:\Program Files\DXKeeper\Reports\<operator>6M grids.txt
        LoadLayout C:\Program Files\DXKeeper\Configurations\Primary.txt

The Modify command designates an item and provide a new value for that item; its operation is comparable to the Modify QSOs panel.  Consider the following  Modify commands:

Modify DXCCid 20
Modify DXCCprefix KH1
Modify CQZ 31
Modify ITUz 61

These commands will change the DXCCid, DXCCprefix, CQZ, and ITUz items of each QSO in the the Log Page Display. If placed after the above Filter command, these four Modify commands would update all pre-1979 QSOs with Baker and Howland Islands to contain the correct country code, DXCC prefix, CQ zone, and ITU zone.

Within the new value, the character sequence <current> represents the item's current value. Thus the commands

Filter (QSO_Begin > #6/21/2003#) and QSO_Begin < #6/22/2003#)
Modify COMMENT <current> (solar flux = 144)

will append (solar flux = 144)to the comment item of every QSO logged on 21-Jun-2003. 

Within the new value, the character sequence '' means "clear the designated item". Thus the commands

Filter Band='6m'
Modify PROP_MODE ''

will clear the propagation mode item logged with every 6m QSO.

Within the new value, the character sequence <capitalized> represents the item's current value with its first letter capitalized. Thus the commands

Filter DXCCprefix = 'F'
Modify QTH <capitalized>

will change a QTH containing paris to Paris in all QSOs with French stations.

Within the new value of a file item, the character sequence <filename> represents the simple filename component of the pathname specified in the current value. Thus the commands

Filter DXCCprefix = 'F'
Modify APP_DXKEEPER_FILE c:\HamRadio\QSO_Files\French\<filename>

will change a QSO's file item from

 c:\dxlab\dxkeeper\QSO_Files\F5IN_Transceiver_Schematic.jpg

to

c:\HamRadio\QSO_Files\French\F5IN_Transceiver_Schematic.jpg

Within the new value, you can reference the contents of any other item in the QSO by enclosing that item's ADIF name in angle brackets. Thus the commands

    Filter true
    Modify PROP_MODE <COMMENT>

would set every QSO's propagation mode to the contents of its comment item.

You can also use the new value field to add or subtract a time interval from the QSO_Begin or QSO_End item of each selected QSO:

Neither fractions nor combinations are permitted; if you want to add 3 hours and 30 minutes to each QSO's start time, for example,  use +210n.

A Modify command will only be executed if the most recent Filter command succeeded; thus the first command in a script file must be a Filter command. After a Modify command is executed, the number of QSOs modified is recorded in the script log file, and then the most recent Filter command is re-executed; this ensures that any subsequent Modify commands are applied to the intended subset of logged QSOs. Prior to execution, the Modify command verifies that the designated item is valid, and that the specified new value for that item is appropriate; any error will prevent the Modify command from being executed, and will be recorded in the script log file.

Modifications made by script execution to any of the following items can require that the current log's Realtime Award Progress and the current Spot Database (if SpotCollector is running) be updated via recomputation:

• Band
• Call
• CQ
• DXCC Prefix
• eQSL Rcvd
• LotW Rcvd
• Mode
• PropMode
• QSL Rcvd
• SatName

If recomputation might be required, DXKeeper will notify you, and offer to initiate the process. If you are planning to execute more scripts that modify logged QSOs, complete those modifications; then initiate recomputation after the last change has been made.

DXKeeper's /Scripts folder contains several preconstructed scripts for updating older QSOs to reflect up-to-date DXCC country codes, DXCC prefixes, CQ zones, and ITU zones. These can be used to correct QSOs that were imported without DXCCID tags, and as examples of script construction.