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

• modify QSOs in the Log Page Display

• specify the layout of the Log Page Display

• generate log reports and award progress reports

• export QSOs from the Log Page Display to a file in ADIF, tab-delimited, or Cabrillo format

Scripts thus enable you to automate frequently-invoked sequences of operations, like this one:

    Filter (Band='6m') and (Mode = 'RTTY')
    Report Grids C:\Program Files\DXKeeper\Reports\6M RTTY grids.txt

    Filter (Band='2m')and (Mode = 'RTTY')
    Report Grids C:\Program Files\DXKeeper\Reports\2M RTTY grids.txt

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 right 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. By default, you'll be prompted to select a script file from DXKeeper's Scripts folder, but if you select a script from a different folder, you'll be prompted to select a script file from that folder the next time you take one of the above actions.

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, displaying them in a Script Progress window. Each executed command is recorded in a script log file with an indication as to its success or failure; when script execution is complete, DXKeeper displays the script log file.

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

Export

The Export command exports sets the Options panel on the Main window's Exports tab and then exports QSOs in the Log Page Display to a specified filename. Its generic format is

    Export Options ExportFilename

Options can be ADIF, TDF, or CABRILLO to set the Options panel  to ADIF, tab-delimited, or Cabrillo respectively.

If the specified ExportFilename already exists, its contents will be replaced.

ExportFilename supports the Filename Substitution Commands described below

Delete

The Delete command deletes the specified filename; its format is

    Delete Filename

The Filename can contain Filename Substitution Commands.

AppendText

The AppendText command appends the specified text to the specified filename, creating the file if it doesn't already exist; its format is

    AppendText "some text" ReportFilename

The text to be appended must be enclosed by double-quotes, and may not contain a double-quote.

The Filename can contain Filename Substitution Commands.

Display

The Display command displays the contents of  the specified filename; its format is

    Display Filename

The Filename can contain Filename Substitution Commands.

Filter

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.

RefineFilter

The RefineFilter command functions like the Filter command but "refines" the Log Page Display filter in force at the time the script containing the RefineFilter command was invoked. If when the script is invoked, the Log Page Display is filtered with the SQL expression

    MODE='CW'

the command

         RefineFilter ( QSO_Begin < #1/1/1979#) and ( call like '*KB6*')

will filter the Log Page Display with the SQL expression

        (MODE='CW') and  ( QSO_Begin < #1/1/1979#) and ( call like '*KB6*')

LoadLayout

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

Modify, ModifyWithoutBackup

The Modify command designates an item and provides a new value for that item. The ModifyWithoutBackup   command is functionally identical, but does not cause DXKeeper to offer to backup your log before running your script. 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 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 <today> is replaced the current UTC date in YYYY-MM-DD format.. 

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 item 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.

Each instance of<newline> will be replaced by a newline character. Thus the commands

Filter true

Modify ADDRESS <CALL><NEWLINE<ADDRESS>

will insert each QSO's callsign into the first line of its address.

You can use the new value field to add or subtract a time interval from the QSO_Begin or QSO_End item of each selected QSO by beginning the new value with + or - and ending the new value with y, m, d, h, n, or s - as illustrated in the table below:

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.

You can use the new value field to computationally modify a QSO's freq or rx_freq item by by specifying a new value that begins with +, -, x, or / - as illustrated in the table below:

• modifying a a QSO's freq item automatically updates its band item
  
• modifying a QSO's rx_freq item automatically updates its rx band item

You can prevent DXKeeper from interpreting a word between square brackets as a "command" by preceding it with a backslash character (\). For example, setting the new value to \<call> would replace the item in each QSO with <call> rather than with the contents of each QSO's callsign item. Note that \<filename> in a File or AudioFile item does not result in removal of the backslash.

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.

Changes that if made manually would change a QSO's Club Log Status item from Y to M do not result in the  Modify or  ModifyWithoutBackup commands changing a QSO's Club Log Status item from Y to M.  You can accomplish this by using a second Modify or  ModifyWithoutBackup command to change the Club Log Status item in the selected QSOs.

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.

Plot

The Plot command conveys all QSOs in the Log Page Display to DXView for display on the world maps(s) it manages.


Report and AppendReport

The Report and AppendReport commands direct the generation of a log or progress report into a specified filename. Their generic formats are

         Report Kind ReportFilename

         AppendReport Kind ReportFilename

Kind can be one of the following values

Both  commands supports the Filename Substitution Commands described below. For example, the commands

        Filter Band='6m'
    Report Grids C:\DXLab\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:\DXLab\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. 

If the specified ReportFilename already exists, the Report command will clear it before populating it with the generated report, whereas the AppendReport command will append the generated report to the existing file; therefore, the  AppendReport command can only be used to generate text reports.  At its completion, the Report command displays the generated report, whereas the AppendReport command does not. In conjunction with the Delete and Display commands, the AppendReport command can be used to place several reports into a single file and then display them, e.g.

delete c:\program files\dxlab suite\dxkeeper\reports\us_states.txt

filter true
appendreport us_states C:\DXLab\DXKeeper\Reports\us_states.txt

filter Mode='SSB'
appendreport us_states C:\DXLab\DXKeeper\Reports\us_states.txt

filter Mode='CW'
appendreport us_states C:\DXLab\DXKeeper\Reports\us_states.txt

filter Mode='RTTY'
appendreport us_states C:\DXLab\DXKeeper\Reports\us_states.txt

display C:\DXLab\DXKeeper\Reports\us_states.txt

Sort

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.

Filename Substitution Commands

The substitution commands can be used in the AppendReport, AppendText, Delete, Display, Export, and Report  script commands:

Exploiting <ReportsFolder> the script above used to illustrate the use of appendreport can be simplified to

delete <ReportsFolder>us_states.txt

filter true
appendreport us_states <ReportsFolder>us_states.txt

filter Mode='SSB'
appendreport us_states <ReportsFolder>us_states.txt

filter Mode='CW'
appendreport us_states <ReportsFolder>us_states.txt

filter Mode='RTTY'
appendreport us_states <ReportsFolder>us_states.txt

display <ReportsFolder>us_states.txt

In addition to being simpler, this script can be exchanged among users without modification to compensate for DXKeeper being installed in different folders from one PC to another.