README file, last modified 24 December 2007


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 Post-installation checks


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 database schema


8. Utilities


9. Credits


10. Feedback


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

The qle-package 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  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) database schema  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 script.

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. Hamlib rig control libraries (optional)
	3. SQLite database

and, optionally:

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

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 Debian, the following Hamlib packages are used:

wk@asus:~$ dpkg --list | grep hamlib

hamlib++-dev  1.2.4-3  Development library to control radio transceivers
hamlib-dev    1.2.4-3  Development library to control radio transceivers
hamlib-doc    1.2.4-3  Documentation for the hamlib radio control library
hamlib-utils  1.2.4-3  Utilities to support the hamlib radio control library
hamlib3       1.2.4-3  Run-time library to control radio transceivers
hamlib3++     1.2.4-1  Run-time library to control radio transceivers
hamlib3-perl  1.2.4-3  Run-time library to control radio transceivers

Note for Mandrake users (non Mandrake: proceed to paragraph 4):

If you decide to roll your own, make sure you compile with
'--enable-perl-binding' to create the Perl module and libraries.

On my Mandrake 10.0 system, the '--prefix=/usr' option is also needed,
to make sure the files go  under /usr/lib/perl5. If you don't do this,
they'll go  to /usr/local/lib/per5, where Perl can't  find them. (This
is possibly a bug)

On my machine, the hamlib 1.2.3 Perl files are in:

/usr/lib/perl5/site_perl/5.8.3/i386-linux-thread-multi/Hamlib.pm
/usr/lib/perl5/site_perl/5.8.3/i386-linux-thread-multi/auto/Hamlib/Hamlib.bs
/usr/lib/perl5/site_perl/5.8.3/i386-linux-thread-multi/auto/Hamlib/Hamlib.so

Warning: On some versions of Hamlib, the 'make uninstall' command does
not remove the Perl bindings... so, when you upgrade, you may have to
remove the old bindings manually.


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. Have Perl and modules mentioned in 3.2/3.3 installed, tested and
   working.

2. Establish that the DBD::SQLite module is installed (see paragraph
   3.4). Verify that the sample database file is OK by running
   'sqlite3 foo3.db'.

3. Make sure Hamlib (paragraph 3.5) is installed. Verify that hamlib is
   working with your rig, by using the 'rigctl -m <model-number> -r
   <serial-port>' utility. Try reading the frequency and mode with 'f'
   and 'm'.

   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.

   If you are using RPC-rig Hamlib (defined in the config file:
   $rigNumber = "1901") and the RPC-rig process is not running, then
   the logger will SEGFAULT. The rpc-rig process must be running for
   the logger to start up.

   The logger program freezes if you turn off the rig so it can no
   longer be polled. To fix this, turn the rig back on.

   Check the Hamlib docs for further info on the installation and use
   of Hamlib. 

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

5. As a regular (non-root) user, copy the qle tarball to your home
   directory. Create the 'qle-<version>' directory and extract 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.
      foo3.db              A sample SQLite3 database.
      README               The 'docs'
      ChangeLog            Shows changes to the program.

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

      myCall Your callsign
      db The full pathname of the file containing the database.
      tablename The name of the table you want to log to.

      useRig Set to '1' if you want to use Hamlib.
      rigPathName Path to serial device used by your rig.
      rigNumber The hamlib number for your rig.
      rigSpeed The CAT interface bit rate for your rig. 

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


4.2 Post-installation checks.
-----------------------------

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.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 'sqlite[3]' 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. List the QSOs with:

	 SELECT * FROM zl2bsj;

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
   rig number and rig device must be the same as defined in the
   qle.conf config file by rigNumber and rigPathname respectively.
   

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. Check that StayOnTop is installed with 'man Tk::StayOnTop'.

7. Initially, you should run up the logger from an X-terminal with the
   command line as below:

         ./qle-<version>.pl --debug=1

   This will produce run-time feedback on various things, which is
   useful for catching problems with support software


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

The logger  starts when you  type './qle-<version>.pl' 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 off  by editing  the configuration
file).

With the  Copyright OK,  the user is  presented with the  main window,
which consists of two panels, known in Perl/Tk-speak as 'frames'.

The 'Log  viewer and  editor' frame  at the top  is used  for viewing,
searching and editing previously made QSOs.

In the bottom  half of the window, the 'New QSO  template' is used for
entering new QSOs.

There is  a status  line, roughly  in the middle  of the  main window,
showing database and user details.

At the very bottom, 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.


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

This 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 QSO 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.

Cabrillo  uses hyphens  for  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.

ADIF   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'.

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

Run-mode contest logging works as follows: call (on CW) 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.  However,   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 detecting hamlib or  a working
rig, and  removes type 'RIG' from  the option menu.  Instead, 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  hamlib  and 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.3 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.4 Changing the database schema
--------------------------------

The easiest way to  change the look of your log is  to 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,  and does  not
require any changes to the database.

If you want to add or delete  fields, or change the names of fields in
the database  you will need to dump  any existing QSOs to  a text file
first, and later load them back  into the new database. This hassle is
avoided if you start with an empty log.

If you decide to  do this, you will also have to  update all arrays in
the  config file.  Some variables  in  the config  file contain  named
references to fields, so if  you change the database field names, then
all these references  will have to be updated,  too. Examples of these
variables are 'defaultSearchField' and 'defaultSerialField'.

The following steps are required to alter the schema:

1. Make a backup of the database file.

2. Make a dump of the exisiting database: from sqlite3, use the

	'.output <filename>'

   and

	'dump <table>'

   commands to dump the database into a text file.

3. Edit the dump  by making changes to the  'CREATE' statements to get
the new schema, and alter  all 'INSERT' statements. You'll need a good
editor with  macro action to  do this :-)  and a working  knowledge of
SQL.

5. Create the  new (empty)  database with 'touch  <new-filename>'. Now
run up sqlite[3] and load the new .dump file using:

        '.read <new-filename>'

6. Make sure the new databse is in good working order with sqlite[3].

7. Edit  qle.conf,  making  sure  *all*  values comply  with  the  new
schema. Make sure 'db' points at the new database...

8. Start up  'qle-<version>.pl --debug=1', search  the log, log  a few
dummy QSOs, check that the dupe window works.

The qle-<version>.pl code does not contain hard-coded field references,
and the process outlined above should work, but is untested because the
field defaults meet the author's requirements already :-)


Example: we  want to  add fields 'country'  and 'continent' to  an old
(before version 0.0.9) table, in order to log DXCC info. Do this:

1. Back up the database file: 'cp  foo3.db foo3.bak.db'

2. Run up sqlite3: 'sqlite3 foo3.db'. Use '.h' to get help.

3. Export table by piping output to file: '.out <file>' and '.dump
<table>'

4. delete table with 'dump <table>;'

5. Quit sqlite3 with '.q'. Now edit  the file; add to the CREATE TABLE
section:

        "country" character varying(20) DEFAULT '' NOT NULL,
        "continent" character varying(5) DEFAULT '' NOT NULL,

and add to each INSERT statement a couple of empty strings (the number
of INSERT items must match  the number of fields). Afterwards, it will
look like this:

INSERT INTO "<table>" VALUES(6,1,2008,2053,'UR7UD','589','','599','',7012\
,'CW','Serge','Kiev','100W/IC775DSP/2EL','100W/INVVEE','n','n',\
'No comment','','');

6. Now  the dump  is  ready to  be  imported. Start  up with  'sqlite3
foo3.db'  and import  the  dump  with '.read  <file>'.  You will  have
recovered the log. Check that all QSOs are there with:

'select count(*) from <table>';

Having added  continent and country fields  to the table,  you need to
make sure  the field  definitions in the  qle config file  are updated
accordingly, or  else the program  won't run. The example  config file
already  contains the  continent  and country  changes,  look for  the
'database section'.


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

adifexport.pl (removed, and built into 0.0.8 and later)
-------------
A perl script  that reads the config file. From this,  it nuts out the
name of the database file and the table name.  It then reads the table
and dumps it to STDOUT in  ADIF format. This script is now obsolete as
the GUI has an ADIF exporter built-in.

adifimport.pl
-------------
A 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.

qle.sh 
------
A start-up script which sets the font to be used by qle.pl. Use
'xlsfonts' to list aviailable fonts. Use showfonts.pl to view them. Edit
the script accordingly.



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

Nate   N0NB   - schema, database and SQLite suggestions.

Gordon ZL2ARN - suggestions and hosting the software.

Jeremy KB8LFA - schema and functional suggestions, ADIF code.



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

knol00@gmail.com



73 - Wilbert, ZL2BSJ.

<EOF>
