README file, last modified 2 January 2009


Contents:

1. Introduction


2. Features


3. Requirements

   3.1 Hardware requirements
   3.2 Software required
   3.3 Perl packages required
   3.4 Database requirements
   3.5 Rig control requirements
   3.6 CW-daemon


4. Installation

       4.1 Quick start
       4.2 Trouble-shooting


5. Use of the QSO logger and log editor

   5.1 Description of 'log viewer and editor' frame

       5.1.1 Searching the log
       5.1.2 Editing log entries
       5.1.3 Deleting log entries
       5.1.4 Exporting log entries to Cabrillo
       5.1.5 Exporting log entries to ADIF

   5.2 New QSO template

   5.3 Casual logging

   5.4 Contest logging

       5.4.1 Run mode
       5.4.2 Search & Pounce mode
       5.4.3 Self-incrementing serials

   5.5 CW checkboxes
   5.6 Time and rig data
   5.7 'type' option menus


6. Summary of commands

       6.1 CW functions
       6.2 All modes
       6.3 Editing fields
       6.4 Editor window


7. Customising the logger

       7.1 Fonts, colours, window size
       7.2 Log view
       7.3 Filtering on data entry
       7.4 Default values
       7.5 Changing the log


8. Utilities


9. Credits


10. Feedback


1. Introduction
---------------

The qle archive contains the program 'qle-<version>.pl': a graphic QSO
log viewer, log editor and QSO logger for amateur radio operators.

'qle' stands  for QSO Logger  and log Editor.  It is a  Perl/Tk script
that  logs (or  modifies) QSOs  directly  in a  fast and  light-weight
SQLite database.

Intended use: CASUAL logging of  rag-chew and contest QSOs. The logger
caters for CW operators. See 'Features' list below.

Table  headings, fonts,  colours and  other  attributes are  set in  a
user-editable configuration  file. The SQLite log  schema supplied may
be  altered to  suit your  taste, provided  the configuration  file is
updated accordingly.

If you  are looking for  a performance contest logger,  consider using
TLF by  PA0R. Similarly,  XLOG (PG4I) and  KLOG (EA4TV) are  very good
general-purpose loggers that are more intuitive to configure and use.


2. Features
-----------

1. Hamlib rig query.  A  Hamlib-interfaced radio is higly recommended,
   unless you are fond of manually keeping track of frequency and mode
   info.

2. For CW contesters: computer-generated CW via 'cwdaemon'. Automatic,
   repetitive CQ-ing.

3. The provided (and recommended)  SQLite3 database logs the following
   items:

   day,  month, year,  UTC, call,  RST sent,  serial number  sent, RST
   received, serial  number received, frequency,  mode, operator, QTH,
   my power, his  power, QSL sent, QSL received,  comment, country and
   continent.

4. On-the-fly dupe checking by band/mode for contesters.

5. Real-time and delayed (post-QSO) data entry.

6. Built-in log searching and log editing.

7. DXCC lookup.  'qle' tries to  guess DXCC country and  continent for
   the station ebing worked. This info is saved with the QSO.

8. Super  check partial,  or  'SCP'.  The prgram  tries  to match  the
   callsign  being  worked  against  master.scp.  Handy  if  you're  a
   contester or DXpeditioner.

9. Complete lack of documentation other  than a README and a commented
   configuration file.

10.The logger does not track scores and has no band-map or DX-cluster
   support. There is  no voice keyer support, and  I have no intention
   to add these  features.  The logger is used  for Casual logging and
   DX-ing only.


3. Requirements
---------------

3.1 Hardware required:
----------------------

I run the logger on an  ASUS 2.1 GHz Athlon notebook computer with 512
MBytes  of  RAM.  A minimum  screen  size  of  1024  x 768  pixels  is
required.

'qle'  was written  for Linux,  but it  allegedly runs  under Windows,
which I no longer use.  Currently, my operating system is the unstable
version 'Etch'  of Debian GNU/Linux, and  I have in the  past used the
logger under Mandrake 10.0 and SuSe 9.0.

Wet-ware required:

In order to successfully install  the logger and the support software,
some system-admin knowledge of Linux is needed.


3.2 Software required: 
----------------------

If you use Debian Linux (highly recommended if you are a ham), you can
get most  of the support  software from .deb  packages on the  DVDs or
from the Debian website.

In  the past,  I have  also used  the qle  logger under  Mandrake 10.0
Community, but the INSTALL instructions in this README assume a Debian
machine. Package names will be different for other distributions.

Basically, 'qle.pl' needs three things to run:
 
	1. Perl interpreter - with some add-on 'modules'
	2. SQLite version 3 database

and, optionally:

	3. Hamlib rig control libraries
        4. cwdaemon for transmitting CW

Hamlib and cwdaemon are recommended  but optional. The logger will not
run without Perl and SQLite.


3.3 Perl packages required: 
---------------------------

The logger is written in the Perl language, and requires the following
(or  later)  distro  packages:

perl 5.8.8-3
perl-base 5.8.8-3
perl-modules 5.8.8-3  (Core Perl modules)
perl-tk 804.027-4     (Perl module providing the Tk graphics library)

In  addition  the  Config::General   module  is  needed  to  read  the
configuration file. It hides in a distro package:

libconfig-general-perl 2.31-2  (Generic Configuration Module)

Finally, the last Perl module  required is the Tk graphics toolkit for
Perl, needed to draw the graphic gadgets on your screen.


3.4 Database requirements:
--------------------------

The logger  must have  access to the  database log-file. This  is done
through a generic Perl-language  interface called 'DBI' which probably
means  'database interface'. This  gives access  to any  SQL database.
The DBI is provided by most Linux distributions as a package; MDk 10.0
and Debian 3.1 do.

The Perl  DBI requires  a database-specific driver  (DBD) in  order to
talk to that  particular database. For SQLite, the  Perl DBD module is
called 'DBD::SQLite'.

The easiest way to obtain both DBI and DBD, is to install the Perl DBI
and the SQLite DBD packages mentioned above if you are a Debian user.

libdbi-perl           1.50-2    Perl5 database interface by Tim Bunce
libdbd-sqlite3-perl   1.11-1    Perl DBI driver
libhk-classes-sqlite  0.8-2     sqlite driver plugin for libhk-classes
libhk-classes-sqlite3 0.8-2     sqlite3 driver plugin for libhk-classes
libsqlite0            2.8.16-1  SQLite shared library
libsqlite3-0          3.2.8-1   SQLite 3 shared library
libsqlite3-dev        3.2.8-1   SQLite 3 development files
sqlite                2.8.16-1  command line interface for SQLite
sqlite3               3.2.8-1   A command line interface for SQLite 3
sqlite3-doc           3.2.8-1   SQLite 3 documentation

The first package is the DBD driver (wrongly called DBI driver in the
info). Required. 

The libhk-classes are  optional, but nice to have if  you want to view
the SQLite database with  KNoda, a graphic database viewer/editor. The
libsqlite libraries are needed.

The 'sqlite3' command-line interface  is highly recommended for making
back-up dumps  of the database. It  is also very handy  for doing more
advanced operations on your log database, such as mass changes. Pretty
much essential.

Foot-note: I use SQLite3. The earlier SQLite2 is incompatible, but you
can  'dump'  the   database  into  a  text  file   from  the  'sqlite'
command-line interface, and then create  a SQLite3 database from it by
reading the dump into the 'sqlite3' command-line program.


3.5 Rig control requirements:
-----------------------------

On my  Debian 'Etch' distro, as  on 15 Dec. 2008  the following Hamlib
1.2.7 packages are used installed:

libhamlib++-dev Development library to control radio transce
libhamlib-dev   Development library to control radio transce
libhamlib-doc   Documentation for the hamlib radio control l
libhamlib-utils Utilities to support the hamlib radio contro
libhamlib2      Run-time library to control radio transceive
libhamlib2++c2  Run-time library to control radio transceive
libhamlib2-tcl  Run-time library to control radio transceive

3.6 CW-daemon
-------------

On Debian, install this (or later) package:

cwdaemon   0.9.3-1   morse daemon for the parallel or serial port

...and start it up (as root) with: '/etc/init.d/cwdaemon start'.


4. Installation.
----------------

4.1 Quick start
----------------

To get the logger up and running, do this:

1. As a  regular (non-root)  user, copy the  qle tarball to  your home
   directory.  Create (and extract to) directory 'qle-<version>' with:

     'tar xvzf qle-<version>.tar.gz'

   The files of interest are:

      qle-<version>.pl     The logger/editor program.
      qle-<version>.conf   The configuration file.
      qle.sh               The startup shell script.
      foo3.db              An example SQLite3 database.
      README               The 'docs'
      ChangeLog            Shows a log of changes to the program.


2. Have Perl and modules mentioned in 3.2/3.3 installed, tested and
   working.

3. Establish that the DBD::SQLite module is installed (see paragraph
   3.4). Verify that the sample database file is OK by running up
   'sqlite3 foo3.db' and executing 'select * from mycall;' Quit with
   '.q'

4. Optional: make sure Hamlib  (paragraph 3.5) is installed. Check the
   Hamlib  docs  for further  info  on  the  installation and  use  of
   Hamlib. Check the man-pages: 'man rigctl' and 'man rigctld'. Verify
   that hamlib is working with your rig, by using the command:

         'rigctl -m<model-number> -s<speed> -r<serial-port>'

   Example:

         'rigctl -m314 -s1200 -r/devttyUSB2'

   ...for an IC725 at 1200 Bd on /dev/ttyUSB2

   Try  reading the  frequency and  mode with  'f' and  'm'.  Quit the
   'rigctl' program with 'q'.  Now you know that Hamlib rig control is
   working, so edit the  'rigtld'  line  in the  startup  shell  script
   'qle.sh', substituting your -m -s and -r values.

   Note:  the logger  *will*  run  without a  connected  rig, but  the
   frequency will be the default  value from the config file. For this
   reason, a working Hamlib-interfaced rig is highy recommended.

5. Optional: if you are a CW op, make sure that cwdaemon is installed,
   working correctly, and running.  See the cwdaemon docs for details.
   Cwdaemon operation  is optional.  If  the daemon can not  be found,
   the keyer will  be disabled, and the logger  will still run without
   ill  effect. If  you don't  operate CW,  set 'noCWDaemon=1'  in the
   config file, which by-passes the cwdaemon PID check.

6. Customise at least the following parameters in the configuration
   file:

      myCall        Your callsign (default 'N0CAL')
      useRig        Set to '0' if you don't want to use Hamlib
      noCwDaemon    Set to '0' if you don't want to transmit CW 
      debug         Set to '0' if you don't need debugging output

   ...and edit  the 'rigctld' line  in the startup  script 'qle.sh'
   for the correct rig model and port device, if you're using Hamlib.

7. As a  non-root user,  run the logger  (with debug output)  from the
   install directory ~/qle-<version> with:
   
      ./qle.sh --debug=1

   Once everything is working as  expected, leave the debug switch out
   and make sure 'debug=0' in the config file and in the startup shell
   script.


4.2 Trouble-shooting
--------------------

(In the following paragraph, <text> needs to be replaced with whatever
it is that you use for this item)

Various checks can be performed to verify that everything is in place:

1. Make  sure   that  the  qle-<version>.pl  script   finds  the  Perl
   interpreter. Run 'which perl' and compare this to the first line in
   qle.pl. On my system, Perl lives in /usr/bin/perl.

2. Check that DBD::SQLite is installed with:

	 'locate DBD/SQLite.pm'

   (You will need to have the 'findutils' package installed, and the
   locate database updated with 'updatedb' as root user, before
   running the command)

3. Check that the sample database file can be read with:

	 'sqlite3 foo3.db'

   You  need  to have  installed  the  separate  'sqlite3' utility  as
   mentioned in paragraph 3.4. Check that the table you have nominated
   in qle.conf does, in fact, exist, with the command:

	 .tables

   ...from inside the sqlite3 program. Now show the QSOs with:

	 SELECT * FROM mycall;

4. Try out hamlib rig control with:

	 rigctl -m<rig-model-number> -r<rig-device>

   ..and read frequency and mode with 'f' and 'm' respectively. The
   
   Once this works, quit the 'rigctl' program. Modify the 'rigctld'
   startup line in de shell script 'qle.sh' to reflect your rig and
   your port device.  Running 'qle.sh' starts the 'rigctld' server up
   in the background and runs up the logger. If the logger won't talk
   to the rig, check that the rigctld server is indeed running with
   'ps ax | grep rigctld'. If it is, try connecting to it from a Linux
   console with: 'telnet localhost 4532' and typing 'f<ENTER>' on the
   command line. You should see a kHz frequency come back.

5. If you are a CW op, check that cwdaemon is loaded and working
   properly. See the cwdaemon docs for details on how to test the
   daemon with the 'netcat' utility.

6. Initially, from an X-terminal, you should run up the logger inside
   the install  directory 'qle-<version>' with the command:

         ./qle.sh --debug=1

   This will  produce run-time feedback on many  processes, useful for
   catching problems.

   The  --debug switch can  be left  off once  the program  is running
   correctly. If you keep getting  debug output on your console, check
   that  --debug=0 inside the  startup script  'qle.sh' and  also that
   'debug 0' in the config file 'qle-<vesrion>.conf'


5. Use of the QSO logger and log editor
---------------------------------------

The logger  starts when you  type './qle.sh' at  the command
prompt from the install directory.

First,  the main window  is shown,  with the  GPL Copyright  window in
front of it  (which can be turned on/off  by editing the configuration
file).

With the  Copyright OK,  the user is  confronted with  (assaulted by?)
several windows

The 'Log viewer and editor'  window is used for viewing, searching and
editing previously made QSOs.

Another  window, the  'New  QSO  template' is  used  for entering  new
QSOs. It contains data entry fields and a dupe check window.

At the  very bottom  of the New  QSO window,  two lines show  the most
commonly   used  pushbuttons  for   entering  a   new  QSO   into  the
template.  The first  line contains  CW function  keys (greyed  out in
non-CW  modes). The  line below  it  shows buttons  that have  general
functionality: e.g. to quit the program.

Lastly,  the SCP  (super check  partial) window  appears,  which shows
known-good  callsigns that  match what  you've typed  in  the callsign
field. The latest  versions of SCP file 'master.scp'  and country file
'cty.dat' can be found on the Internet, at:

   http://www.k5zd.com/scp/index.html

and:

   http://www.country-files.com/cty/index.htm

..respectively.

Grab  the 'Win-test  ASCII file'  master.scp and  the CT10  version of
cty.dat


5.1 Description of 'log viewer and editor' frame
------------------------------------------------

5.1.1 Searching the log
-----------------------

The  frame  shows a  view  of  the log  in  a  listbox, which  becomes
scrollable if the log view exceeds the size of the listbox.


 Show recent QSOs:
 ----------------- 

Typically, the log  view shows 'most recent' QSOs.  The number of QSOs
shown depends  on the  value of 'rNumber'  in the  configuration file.
The 'show recent QSOs' view is updated every time a QSO is logged.

 Search by string:
 ----------------- 

Alternatively, the log view listbox can  be made to show the result of
a log search if checkbox 'search by string' is ticked instead of 'show
recent QSOs'. This is handy when replying to incoming QSL cards.

The  default search  mode ('show  recent'  or 'search  by string')  is
determined by variable 'defaultMode' in the configuration file.

A 'search by string' is performed by ticking the checkbox and entering
a search string  in the entry box below it. Select  the field you want
to search. The  default search field is set  in the configuration file
by  assigning   to  'defaultSearchField'   a  value  from   the  array
'fieldNames', also in the config file.

A  log search  can be  'strict' (case-sensitive,  requiring  a perfect
match)  or 'loose': case  does not  matter, and  '*' wildcards  can be
embedded in the search string to achieve an approximate match. Whether
'strict' or 'loose'  is the default is set  through the 'defaultMatch'
variable in the configuration file.

 Tweaking the appearance of the log view:
 ----------------------------------------

Fields can be made not to appear in the log view listbox. This is
determined by the values of array 'logSHowFields' in the configuration
file.

By default,  most field values  appear left-aligned in the  columns of
the  log view  listbox.   If you  don't  want this,  change the  array
'rightAligned' in the configuration file.


5.1.2 Editing log entries
-------------------------

A  QSO in  the  log view  listbox can  be  loaded into  the editor  by
double-clicking it. Alternatively, TAB or SHIFT-TAB can move the focus
to the  listbox, and the keyboard arrow  keys can be used  to move the
highligt onto the  QSO we want to edit, which can  then be loaded into
the editor by typing ALT-E.

Doing any of these things pops the QSO up in a separate box: the 'Edit
Window'. Changes can be made and saved, or the editor can be dismissed
without saving by:

1. Clicking the 'Discard changes' button 2. Hitting the Escape key, or
3. Typing 'ALT-C' or 4. Typing 'ALT-F4'.

You'll  notice  that  the  editor  stops you  from  entering  unwanted
characters into fields.

In the  configuration file,  there is an  array called  'intAll' which
indicates that a field must be all numbers if the value for that field
is '1'.  Any character typed that is  not a number will  be ignored by
the field editor.

Other  arrays  of  interest  that  affect  data  entry  are  'capAll',
'capStart'  and  'spaceOK'.  Check  the  respective  comments  in  the
configuration file for further details.


5.1.3 Deleting log entries
--------------------------

Existing QSOs  can be  removed from the  log database  by highlighting
them in the log view window and clikcing on the 'Delete QSO' button or
typing 'ALT-D'


5.1.4 Exporting log entries to Cabrillo
---------------------------------------

The program will export logged  QSOs to Cabrillo format. Highlight the
QSOs you want to export and  click on 'Export QSOs'. The export dialog
pops up,  click 'Export to  Cabrillo format' to proceed.  The exporter
(over)-writes  the  file  you  specified  in  the  config  file  under
'cabrilloExportFileName'.

The config  file contains  a section of  Cabrillo headers that  can be
customised in  the config file,  or alternatively, after  the Cabrillo
log has been written out.

The exporter simply grabs fields from  each QSO and puts them into the
Cabrillo format. To do this, it looks up field names as defined by the
cabrilloExport  lines  in  the  config file.   If  the  cabrilloExport
statement contains  a valid field  name, the exporter  retrieves those
fields   from   the  log.    Otherwise,   the   exporter  treats   the
cabrilloExport-defined string  as a constant  and inserts it  into the
Cabrillo QSO  line. E.g: 'cabrilloExport ZL2BSJ'  will insert 'ZL2BSJ'
into the Cabrillo  QSO line.  The exporter retrieves  fields (and puts
them  into the  Cabrillo dump)  in the  same order  in which  they are
listed in the config file.

The Cabrillo  file can  be made  to look 'readable'  by lining  up the
various columns.  This  is achieved by adding a  'format spec' to each
cabrilloExport item.  E.g:  'cabrilloExport call:-10s' will insert the
field 'call'. It  will treat the call as a string  (hence the 's') and
pad  it out to  10 characters  using blank  spaces. It  will left-hand
align the call (the '-'). The ':' separates the field name 'call' from
the format specifier. Do not  use spaces between field name and format
spec, or inside the format spec.

The  formatting only recognises  strings ('s')  and digits  ('d'). The
latter are  padded with  zeros.  E.g: 'cabrilloExport  nr_snt:3d' will
print the field 'nr_snt' as a number  and build it up to 3 digits with
leading zeros. The number  will default to right-hand alignment, which
is what we want for decimals.

The  Cabrillo format  calls for  the use  of hyphens  in  date stamps:
'yyyy-mm-dd'.   The  Cabrillo exporter  looks  for  the 'isMonth'  and
'isYear' statements in the config file to identify the 'mm' and 'yyyy'
fields and to add the hyphen.

There does not seem to  be a 'universal' Cabrillo format for contests,
so you  may have to tweak the  order in which fields  are listed under
the cabrilloExport statements in the config file.


5.1.5 Exporting log entries to ADIF
-----------------------------------

The program will export logged QSOs to ADIF format. Highlight the QSOs
you want to export and click  on 'Export QSOs'. The export dialog pops
up,  click   'Export  to  ADIF   format'  to  proceed.   The  exporter
(over)-writes  the  file  you  specified  in  the  config  file  under
'adifExportFileName'.

The  config  file contains  a  section of  ADIF  headers  that can  be
customised in  the config file,  or alternatively, after the  ADIF log
has been written out.

The exporter simply grabs fields from  each QSO and puts them into the
ADIF format.   To do this, it looks  up field names as  defined by the
adifExport  lines in  the config  file.  If  the  adifExport statement
contains a  valid field name,  the exporter retrieves that  field from
the log. Otherwise, the  exporter treats the adifExport-defined string
as a constant and inserts it  into the ADIF QSO line. E.g:

    adifExport = STX:32

...will  add ADIF  field 'STX'  and assign  value '32'  to it  in each
exported QSO line.

The ADIF exporter retrieves fields (and puts them into the ADIF QSO in
the same order in which they are listed in the config file.

The ADIF format  is particular about date stamps,  they must look like
'yyyymmdd'.   The default  'qle'  database records  dates in  separate
fields, as 'yyyy', 'mm' and  'dd' respectively. So, the exporter needs
to  know  what  those fields  are,  and  it  looks for  the  'isYear',
'isMonth' and 'isDay' directives  in the config file. Any 'adifExport'
directives for these  fields are ignored, and the  exporter builds the
ADIF  'yyyymmdd' string,  which is  written out  under  the 'QSO_DATE'
label.

Another  field that can  cause trouble  is the  QRG field  (ADIF wants
wavelength, or  'band' in meters)  The exporter looks for  the 'isKhz'
directive in  the config  file, retrieves the  QRG and converts  it to
meters according  to the lookup  table 'bandLimits'. The band  is then
saved under the ADIF label 'BAND' as e.g '20m'.

The exporter will also export integer khz ('14123') to MHz (14.123) as
required for  the ADIF field  FREQ, provided the 'iskHz'  directive is
used (see above).

It is worth  mentioning that the ADIF exporter  does not export fields
whose contents is empty. E.g. <STX:0> is omitted.

See  the   embedded  comments  in  the   configuration  file  (section
'adifExport') for  further details. Again: the  'adifExport' table may
need to be tweaked to produce ADIF that suits your purpose.


5.2 New QSO template
--------------------

The  'New  QSO  template' is  used  for  entering  new QSOs  into  the
database. At the  top are a row of checkbuttons.  Below it are columns
of  data fields,  with labels  on the  left, and  option menus  on the
right. Embedded in the middle is the dupe window.

Underneath  it all  is  a row  of  pushbuttons for  CW operators,  and
another row  of general-purpose buttons for logging  the QSO, quitting
the program etc.

The  start-up state  of the  top-row checkbuttons  can be  set  in the
configuration  file  (change   the  values  of  'useRig',  'utcClock',
'abbrevNum' and 'leadingZeros').  The text in some of  the CW function
keys can also be changed, check the CW section in the config file.


5.3 Casual logging
------------------

The general logging procedure is this: at the start of a QSO, you jump
to the  callsign field in the  'new QSO template' with  'ALT-C', or by
clicking on the field, or by tabbing into it.

Enter the callsign of the station worked. Use the TAB key to switch to
the  'RST received'  field.  Type  the report  received.  The TAB  and
SHIFT-TAB  keys will  move you  around the  other fields.  Alter those
fields as required.

When you are happy with the QSO, log it by hitting RETURN.

Once the QSO  is been logged into the database, it  will appear in the
'log  view window', provided  the 'show  recent QSOs'  checkbutton has
been ticked. The QSO counter on the centre status line will increment,
and the QSO editor is ready for a new entry, showing empty fields.


5.4 Contest logging
-------------------

On  SSB, ignore  the  references  to the  CW  function keys  mentioned
below. Otherwise, operation is identical.


5.4.1 Run mode
---------------

Logging contest QSOs in 'run-mode'  works as follows: In CW, call 'CQ'
by pressing 'F1'. You are in run-mode, taking calls.

When someone  calls you, type their  callsign and hit  F12. The logger
fires  off in  CW the  callsign  copied, followed  by the  RST and  an
optional number.

Copy the  'RST received', TAB to  the appropriate fields  to enter RST
received and the  exchange. Now hit 'ALT-RETURN' to  transmit the 'TU'
message and to save the QSO.

The log view listbox will scroll to show the newly added QSO, provided
the 'show recent QSOs' checkbutton was ticked. This tells you that the
QSO is now in the database.


5.4.2 Search & Pounce mode
--------------------------

When you operate  Search and Pounce, you have the DX  lined up on your
receiver.

Jump to  the callsign  field with  'ALT-C' or click  on it.  Enter the
callsign. As you do this, the logger will dupe-check the log, and show
other band/modes in the 'Dupe Sheet'  window. If the station is a dupe
on the current band/mode, the callsign field background will turn red.

Now, on  CW, place your  call with function  key 'F4'. The  DX station
comes back with your callsign,  report and number, which you copy into
the correct entry boxes (use TAB or SHIFT-TAB to get there).

Respond with your RST and number by pressing F2.

When the  DX confirms  with 'TU',  you log the  QSO silently  with the
'RETURN' key, and the new log entry  will show up in the log view list
provided 'show recent QSOs' is checked.



5.4.3 Self-incrementing serials
-------------------------------

In a contest, you often give out a serial number. To get 'qle' to do
this for you, do two things:

1. Tell  'qle' which  field contains  the  serial number.  Do this  by
setting variable 'defaultSerial' to the name of that field. This makes
type '+1' available on the option menu for that field.

2. Start up qle. With the field in '---' mode, enter a base serial
number. The serial field can now be made to self-increment by setting
the field type to '+1' using the option menu.

The  serial field  can  be made  to start  up  as type  '+1' if  array
fieldTypes  is  set  up  accordingly  in  the  config  file,  provided
'defaultSerial' also points to the field.

The value  of the serial  contest number is  lost when the  program is
shut down, so  the program tries to recover  it from previously-logged
QSOs, provided it is a numerical.  If you don't want this, a value can
be  pre-loaded from array  'defaultValues' in  the config  file, which
becomes the new base value upon program start-up.

At any stage, a base value can  be typed in if the field type is first
changed to  '---'. 'By changing the  field back to '+1'  the new value
becomes the base number.



5.5 CW checkboxes
-----------------

 Leading Zeros
 -------------

If '0',  leading zeros  in the number  sent are not  transmitted. E.g:
'599001' is transmitted as '5991' abbreviated numbers.

The start-up  state of this checkbox  is set by  'leadingZeros' in the
config file. The values in array 'lzFields' determine which fields are
subjected to the 'leading zeros' treatment.

 Abbreviate #
 ------------

If '1', '0' is sent as 'a' and '9' is sent as 'n'. E.g: '599001' is
transmitted as '5nnaa1'.

The start-up  state is determined  by 'abbrevNum' in the  config file.
The 'abbreviate  #' function affects  only those fields listed  by the
'abbrevFields' array in the config file.

'Leading  zeros' and  'abbreviate #'  typically only  affects  the RST
sent, and the  number sent. The logger stores the  serial as a number,
which means that any leading zeros are lost ('084' is logged as '84').


5.6 Time and rig data
---------------------

 'Use UTC clock'
 ---------------

Used  for logging  in real-time.  The logger  calculates UTC  from the
computer clock and puts it  in the date/time fields automatically. The
fields can no longer be manually changed.

If you want to log QSOs after the event, uncheck this box, and you can
manually set type and contents on date/time related fields.

'Use UTC clock' overrides pre-defined field types for those fields, as
defined by array fieldTypes in the config file.

The variable 'utcClock' in the  config file defines the start-up state
of the checkbox.

 Using a rig interface
 ---------------------

If  you don't have  a rig  connected, set  variable 'useRig=0'  in the
config file.  This prevents 'qle'  from attempting to detect a working
rig. It also  removes type 'RIG' from the option  menu.  Now, the user
can put values in the mode and frequency fields and lock or carry them
by selecting the approriate type from the option menu.

If  you do have  a rig  connected, set  the value  of 'useRig'  in the
config file.  The program looks for the hamlib 'rigctld' server with a
working rig at start-up. If  successful, rig-related fields come up as
type 'RIG'.  If unsuccessful, type  RIG is unavailable and  the fields
default as  per array  fieldTypes in the  config file. If  the default
type is also 'RIG', a warning pops up, and the fields become 'CAR'.

The  array 'rigData'  in  the  config file  defines  which fields  are
affected by the 'use rig' function.


5.7 'type' option menus
-----------------------

The 'type' option  menu determines what happens to  the field contents
when  you log the  QSO. There  are several  'types': LCK,  CAR, '---',
'+1', UTC and RIG.

Fields of  type '---' type  are wiped clear  after a new QSO  has been
logged, or when the template is wiped with 'ALT-W'.

On program  start-up, if a  default is defined  in the config  file in
array defaultValues,  then that value  is loaded into the  field entry
box.

If the field type is locked  ('LCK'), the value that is present in the
field at the time of locking becomes permanent for the duration of the
session, and the field entry box is made inaccessible to the user.

Fields of  type carry-over or 'CAR'  have the field  value retained at
the  time of  logging  a QSO.  However,  the field  entry box  remains
accessible at all times, so the carry value can be altered by the user
on the fly.

The start-up type of each field entry box can be pre-set in the config
file through array 'fieldTypes'.

If, according to array rigData  in the config file, the field contains
rig  data  (frequency or  mode  data),  then  the type  'RIG'  becomes
available.  Selecting type  'RIG'  makes the  field inaccessible;  the
program puts in the correct value.



6. Summary of commands 
----------------------

6.1 CW functions
----------------

F1		CQ
F2		599 + NR
F3		TU  + myCall
F4		myCall
F5		call
F6		CL?
F7		?
F12             call + 599 + NR
ALT-K           CW keyboard mode
ALT-RETURN      Save QSO + TU
Escape          Abort CW transmission

6.2 All modes
-------------

SPACEBAR        Press currently selected button.
SHIFT-TAB       Move to previous field or widget
TAB             Move to next field or widget

ALT-A           Toggle 'auto' checkbox (automatic, repetitive CQ).
ALT-B           Toggle 'abbreviate' checkbox.
ALT-L	        Toggle 'leading zeros' checkbox.
ALT-W	        Wipe QSO template.
ALT-S	        see 'RETURN'.
ALT-X	        Quit logger.
RETURN	        Update UTC and rig info, log QSO silently.

ALT-R	        Refresh log view if 'search by string' is active and
                a search string has been entered.
Escape          Universal 'cancel/dismiss' for all dialogs. Cancels CW.


If a QSO has been high-lighted in the log view (by double-clicking):

ALT-D	        Delete selected QSO(s)
ALT-E	        Edit   selected QSO(s).
ALT-P	        Export selected QSO(s).

6.3 Editing fields:
-------------------

BACKSPACE	Delete previous character

CTLR-B		Back up cursor
LEFT-arrow	Back up cursor

CTRL-F		Move cursor right
RIGHT-arrow	Move cursor right

CTRL-E		Move to end of field
END		Move to end of field

CTRL-A		Move to start of field
HOME		Move to start of field

CTRL-K		Delete from cursor to end of field

DEL		Delete current character


6.4 Editor Window
-----------------

ALT-Q		Update 'QSL sent' and 'QSL received' status.
ALT-S		Save changes.
ALT-C		Discard changes.
Escape		Discard changes.


7. Customising the logger
-------------------------

Changes can  be made to the  logger by editing  the configuration file
'qle.conf' followed by a program re-start.

The  config file  is  extensively commented.   Make  a back-up  before
changing anything, breaking the  config syntax will prevent the logger
from running.

If there is  something you don't like, have a  look through the config
file.  Changes are  it  can be  customised.  Some of  the more  common
options are listed below:


7.1 Fonts, colours, window size
-------------------------------

Settings can be found in the 'fonts and colours' section of the config
file. The  utilities 'showcolor.pl' and 'showfonts.pl' can  be used to
nut out the values you want to use.

I run  up the logger  from a shell  script, which also  determines the
default font:

  perl qle.pl -font "terminus-bold-14"

See the  example script qle.sh


7.2 Log view
------------

The  size of  the 'most  recent QSOs'  log view  is set  by 'rNumber'.
Ascending or descending sorting  is determined by the 'orderBy' value,
which is in fact an SQL expression.

A similar value in 'dupeOrderBy' configures the dupe window.

The log view  window height can be adjusted  with 'hList_height'.  The
array 'showLogFields' inidicates which fields  show up in the log view
window. A  similar array (dupeShowFields)  does the same for  the dupe
window.

Some  fields are  best displayed  against the  right-hand  margin. The
array 'rightAligned' determines those fields.


7.3 Filtering on data entry
---------------------------

Some fields should not contain  stray spaces, to prevent problems with
log searches. The array 'spaceOK'  defines the fields that will accept
whitespaces. The 'comment' field is an example of a field which should
allow whitespaces.

Certain   fields  should   start  with   upper-case.  E.g:   'qth'  or
'op'. Determined by array 'capStart'.

Other  values  that change  filtering  are  intAll, capAll,  capStart,
fieldTypes. Fields  listed in array 'mustHave' require  a value before
the QSO is logged.


7.4 Default values
------------------

Array 'defaultValues'  in the config file provides  default values for
the new QSO  fields. When the program is running,  you can change this
behaviour on-the-fly  by entering a different value  and locking (LCK)
it, or by changing the type of the field to 'CAR' to carry-over.


7.5 Changing the log
--------------------

You can change the  name under which  a field  shows up on  the logger
screen. This is done by  altering the array 'fieldDescr' in the config
file. Doing this does not require any changes to the database.

Things like adding or delete  fields, or change the names of fields
inside the database table are a major operation that cannot be done
from inside 'qle'.

Changing an  SQLite3 database table is  beyond the scope  of the 'qle'
logger. See the SQLite website at http://www.sqlite.org/ for pointers.

It  should be  explained  that there  is  normally no  reason to  make
database changes. I log  all my QSOs to one table so  that, if I get a
QSL card, I  only have to search that one table.  To extract a contest
log, I highlight and export the appropriate QSOs to Cabrilo or ADIF.

Should you  nevertheless decide to  make changes to the  database, you
will  also have  to  update the  config  file to  reflect the  altered
table. It can be done. Make sure you create a backup first. Good luck.


8. Utilities 
------------

adifimport.pl 
-------------
An example perl script that reads an ADIF file. From this, it extracts
QSOs and dumps them to STDOUT as SQL statements.

You can make the 'sqlite3' program read these SQL statements, which
will add the QSOs to your database log. Use the '.read <filename>'
command.

cabrilloimport.pl
-----------------
As adifimport, but for Cabrillo.

showcolors.pl
-------------
Run this Perl code to see what colours are available on your
machine. Use these colour names in the config file.

showfonts.pl
------------
Run this Perl code to see what fonts are available on your
machine. Use these font names in the qle start-up script (see chapter
7.1)

makelog.sql 
-----------
The SQL  code in  this file  can be read  by the  command-line program
'sqlite3' to create the default  log table. Use the '.read <filename>'
command to execute the script  from within 'sqlite3'.

As an  example of  the use of  the script: edit  makelog.sql, changing
"pe7t" to "<your call>" to create  a new (empty) table by the the name
of <yourcall>. Execute  'makelog.sql' as per above. Then  edit 'db' in
the config file so that 'qle' will read it.

qle.sh 
------
The  recommended start-up script  for 'qle'  which starts  the rigctld
server and kicks  off the logger. On exit, it also kills 'rigctld'.

The  'qle.sh' script  sets  the font  to  be used  by  'qle'. To  view
avaiable fonts,  use 'xlsfonts'.  Use showfonts.pl to  view them. Edit
the 'qle.sh' script accordingly.



9. Credits
----------

Nate   N0NB   - schema, database and SQLite suggestions.

Gordon ZL2ARN - user suggestions.

Jeremy KB8LFA - schema and functional suggestions, ADIF code.



10. Feedback
-----------

knol00 at gmail.com



73 - Wilbert, ZL2BSJ.

<EOF>
