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
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 .
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
The Delete command deletes the specified filename; its format is
Delete Filename
The Filename can
contain Filename Substitution
Commands.
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.
The Display command displays the contents of the specified filename; its format is
Display Filename
The Filename can contain Filename Substitution 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 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*')
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 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.
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
|
ARRL_entities_submission | text | submission report showing
confirmed entities defined by the ARRL
|
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 |
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
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 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.