Filtering, Modifying, and Reporting with Scripts

DXKeeper Online Help Contents

 

A Script is a text file containing lines of commands that

SQL expressions used when filtering or sorting can reference any of the items present in each logged QSO.

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

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*')


ClearNeeded

The ClearNeeded command sets the Needed item to N in each QSO in the Log Page Display


SetNeeded

The SetNeeded command examines each QSO in the Log Page Display and sets its Needed item to Y if confirmation of the QSO would advance award progress towards the DXCC, IOTA, VUCC, WAS, WAZ, or WPX awards on the bands and modes you're pursuing them; it then filters the Log Page Display to contain only QSOs whose Needed items are set to Y. This operation does not exclude QSOs that you've marked invalid for awards, or QSOs that you've indicated cannot be confirmed; if you want such QSOs excluded, appropriately filter the  Log Page Display before invoking SetNeeded.


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:

New item value

Effect
+1y adds one year
-1m subtracts one month
+3d adds 3 days
-2h  subtracts 2 hours
+5n adds 5 minutes
+3s adds 3 seconds

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:

New item value

Effect
+ 36 adds 36 MHz
- .1 subtracts 100 kHz
x 1000 multiplies by 1000
/ 1000 divides by 1000

 

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:

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

Kind Report Format Description
AJA text All Japan (AJA) progress report
ARRL_entities_progress text progress report showing worked/confirmed status for each entity defined by the ARRL
  • can be used to generate progress reports for a variety of entity-based awards, e.g. BARTG
  • the filename component of ReportFilename is used as the generated report's title
ARRL_entities_submission text submission report showing confirmed entities defined by the ARRL
  • can be used to generate submission reports for a variety of entity-based awards, e.g. BARTG
  • the filename component of ReportFilename is used as the generated report's title
Canadian_Provinces text RAC Canadaward progress report
CQDX text CQ DX progress report
DDFM text REF Diplôme des Départements Français de la Métropole progress report
DOK text DARC DOK progress report
DXCC text DXCC progress report
Fields text CQ Field progress report
Grids text Maidenhead Grid Squares progress report
GridChase text ARRL International Grid Chase progress report
IOTA text Islands On The Air progress report
JCC text Japan Century Cities (JCC) progress report
JCG text Japan Century Guns (JCG) progress report
Holyland text Holyland progress report
KDN text Korean District Number progress report
KDN_submission text Korean District Number submission report
Log text one entry for each QSO visible in the Log Page Display
Marathon text CQ DX Marathon progress report for the current year
NPOTA text National Parks On The Air progress report
RDA text RDA Russian District Award progress report
RDA_submission text RDA Russian District Award submission report
QRZ-DX-World text QRZ DX World progress report
QRZ-United-States text QRZ United States progress report
SOTA text Summits on the Air Chaser progress report
SOTA_Activator text Summits on the Air Activator progress report
SRR text SRR Russian Oblast Award progress report
SRR_submission text SRR Russian Oblast Award submission report
Uniques_BandTotal text Unique Callsigns report in descending order of Bands worked
Uniques_Callsign text Unique Callsigns report in Callsign order
Uniques_QSO text Unique Callsigns report in descending order of Mixed QSO count
User0 text User item 0 progress report
User1 text User item 1 progress report
User2 text User item 2 progress report
User3 text User item 3 progress report
User4 text User item 4 progress report
User5 text User item 5 progress report
User6 text User item 6 progress report
User7 text User item 7 progress report
US_States text US, Alaskan, and Hawaiian States progress report
US_Counties text CQ United States of America Counties progress report
VUCC text VUCC progress report (governed by the VUCC Bands & Modes panel)
WAB text Worked All Britain progress report
WABP text Worked All Belgian Provinces progress report
WABP_submission text Worked All Belgian Provinces submission report
WAC text ARRL Worked All Continents progress report
WAE text DARC Worked All Europe progress report
WAJA text Worked All Japan Prefectures (WAJA) progress report
WAHUC text Worked All Hungarian Counties progress report
WAIP text Worked All Italian Provinces progress report
WAS text ARRL Worked All States multi-band, multi-mode progress report (governed by the WAS Bands & Modes panel)
WIA text Wireless Institute of Australia's DXCC Award progress report
WITU HTML Worked ITU Zones progress report
WAZ HTML CQ Worked All Zones progress report (governed by the WAZ Bands & Modes panel)
WAZ-summary text CQ Worked All Zones summary report
WPX text CQ Worked All Prefixes progress report (governed by the WPX Bands & Modes panel)
WPX-summary HTML CQ Worked All Prefixes summary report
WPX-submission text CQ Worked All Prefixes submission report
YASME text Worked All YASME Operations progress report

 

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:

Substitution command Replacement
<stationcallsign> the Default station callsign 
<operator> the Default operator callsign
<ownercallsign> the Default owner callsign 
<date> the current UTC date in the format dd-mmm-yyyy (e.g., 25-JAN-1952)
<ISOdate> the current UTC date in the format yyyy-mm-dd (e.g., 1952-01-25)
<ReportsFolder> the pathname of DXKeeper's Reports folder followed by a \

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.