LoTW Command Line
Logbook of the World - TQSL Command Line
The TQSL program can be given command-line options that tell it to perform actions. This is intended to allow other programs (such as logging applications) to launch TQSL to sign QSO data files.
The command-line help file from TQSL describes the available options.
On the Windows platorm, the path to the executable file, TQSL.EXE, can be found by inspecting the value of the registry key:
HKLM\Software\TrustedQSL\InstallPath
Starting with V1.11, TQSL.EXE includes a VERSIONINFO resource that programs can inspect to determine the version.
On the Linux platform, programs should look for the tqsl file in the normal system executable locations, /usr/bin and /usr/local/bin. Packagers may, of course, choose other locations to install the software.
Under OS X, the application is normally self-contained in a bundle and provided in a .dmg file. Users may drag the file to the desktop, the Applications folder, or to a location of their choosing.
TQSL Command-Line Help File (Note: Options described below are for TQSL V1.14)
Command Line Interface
When starting TQSL, you may specify command line options that
- initiate the definition or editing of a Station Location
- initiate the signing of a log file
- direct that a signed log file be uploaded to LoTW via the internet
Most command line options are single-letter switches, some of which require an argument; such arguments should be separated from the switch letter by one or more spaces. Arguments that contain spaces or other shell-special characters should be quoted in a manner suitable for the operating system and shell that's being used. If more than one command line switch is specified, each switch must be separated from the preceding switch by one or more spaces.
A filename not preceded by a switch is assumed to be the name of a log file whose QSOs are to be signed.
After taking the actions specified by command line options, TQSL will enter its menu-driven mode of operation unless the -q or -x switch is present, in which case it will terminate.
|
Option |
Description |
|
-a |
The action to be taken if a duplicate or out-of-date-range QSO is encountered while signing a log file's QSOs: If no -a switch is specified and a duplicate or out-of-date-range QSO is encountered while signing QSOs, a dialog will be provided that prompts the user to specify how to proceed. |
|
-d |
Suppress the date-range dialog; if this switch is present, the QSO date-range dialog will not be displayed before signing a log. |
|
-h |
Display command line help. |
|
-l Station_Location |
Select a defined Station Location to be used when signing log files. If the specified Station Location contains embedded spaces, it must be quoted in a manner suitable for the operating system and shell that's being used. If the specified Station Location doesn't exist, no QSOs will be signed or uploaded unless -s is also specified. If -l is not present and a log file is being signed, a dialog will be provided that prompts the user to select a Station Location. |
|
-o Filename |
Specify the name of the digitally signed log file to be created. If the specified Filename contains embedded spaces, it must be quoted in a manner suitable for the operating system and shell that's being used. If -o is not present, the specified log filename with its extension set to .tq8 will be used. |
|
-p Password |
Specify the password that gains access to a password-protected Callsign Certificate when signing a log file. If the specified Password contains embedded spaces or other shell-special characters, it must be quoted in a manner suitable for the operating system and shell that's being used. If -p is not present, a log file is being signed, and the specified or selected Station Location includes a password-protected Callsign Certificate, a dialog will be provided that prompts the user to specify the password. |
|
-q |
Operate in batch mode: status information will be routed to stderr, and TQSL will terminate after taking the actions specified by command line options. |
|
-s |
If the -l switch is also present, a dialog will be provided that enables the specified Station Location to be edited; otherwise, a dialog will be provided that enables a new Station Location to be defined. |
|
-u |
Instead of saving the digitally signed log file, upload it to LoTW over the Internet. After processing, the uploaded file will be shown in LoTW's Your Activity list with the specified filename preceded by <TQSLUpl YYYYMMDD-HHMM>, where YYYY is the current year, MM is the current month, DD is the current day, HH is the current hour, and MM is the current minute. |
|
-v |
Display TQSL version information, and terminate. |
|
-x |
Operate in batch mode: status information will be routed to stderr, and TQSL will terminate after taking the actions specified by command line options. |
|
Filename |
A command line option that is not a single-letter switch or the argument associated with a single-letter switch will be considered the name of the ADIF or Cabrillo log file to be digitally signed using the specified or selected Station Location. If the specified Filename contains embedded spaces, it must be quoted in a manner suitable for the operating system and shell that's being used. If -u is present, the resulting signed log file will be uploaded to LoTW via the internet. Otherwise, the resulting signed log file will be saved in the Filename specified by the -o switch; if -o is not present, the resulting log file will be saved in the same directory as the log file using the .tq8 extension, overwriting any existing .tq8 file of the same name. |
Invocation Examples:
Without displaying the QSO date-range dialog and ignoring duplicate QSOs, digitally sign the "cqww log.adi" log file using the "CQWW Portable" Station Location, upload the digitally signed log file to LoTW, route stderr to the file results.txt and then terminate:
tqsl -d -u -a new -x -l "CQWW Portable" "cqww log.adi" 2>results.txt
Edit the "Home" station location before beginning menu-driven operation:
tqsl -l Home -s
Add a station location, and then terminate:
tqsl -s -x
Status Information
If invoked with -q or -x, status information will be routed to stderr. The last line of stderr will have the following format: HH:MM:SS AM/PM Final Status: Description (Code) where
- HH:MM:SS AM/PM is the timestamp
- Description is a textual summary the status that contains no left or right parenthesis
- Code is an integer uniquely identifying the status, as described in the following table
|
Code |
Description |
|
0 |
success: all qsos submitted were signed and saved or signed and uploaded |
|
1 |
cancelled by user |
|
2 |
rejected by LoTW |
|
3 |
unexpected response from TQSL server |
|
4 |
TQSL error |
|
5 |
TQSLlib error |
|
6 |
unable to open input file |
|
7 |
unable to open output file |
|
8 |
all QSOs were duplicates or out of date range |
|
9 |
some QSOs were duplicates or out of date range |
|
10 |
command syntax error |
|
11 |
LoTW Connection error (no network or LoTW is unreachable) |
Status Examples:
05:57:39 PM: Warning: Signing cancelled
05:57:39 PM: No records output
05:57:39 PM: Final Status: cancelled by user (1)
06:05:56 PM: /home/rmurphy/k1mu.adi: 414 QSO records were duplicates
06:05:56 PM: /home/rmurphy/k1mu.adi: wrote 1 records to /home/rmurphy/k1mu.tq8
06:05:56 PM: /home/rmurphy/k1mu.tq8 is ready to be emailed or uploaded.
Note: TQSL assumes that this file will be uploaded to LoTW.
Resubmitting these QSOs will cause them to be reported as duplicates.
06:05:56 PM: Final Status: Some QSOs were duplicates or out of date range (9)
