Log It! Version 1.42 School Club Roundup Logging Software Programmer: Nicholas Radtke (KC7MOD) radtken@aztecfreenet.org Table of Contents License Agreement ------------------------------------- 1 System Requirements ----------------------------------- 2 What is JAVA? ----------------------------------------- 3 Overview ---------------------------------------------- 4 Running Log It! --------------------------------------- 5 Running the Server and Client on the Same Computer --- 5.1 Running the Server ----------------------------------- 5.2 Running the Client ----------------------------------- 5.3 Using the Program ------------------------------------- 6 Troubleshooting --------------------------------------- 7 1. License Agreement This is free software. No responsibility is accepted for any damage that may be inflicted (directly or indirectly) to your system. Comments, questions, etc. are encouraged and may be sent to the author, Nicholas Radtke (KC7MOD) at radtken@aztecfreenet.org. 2. System Requirements -TCP/IP network protocol -JAVA Virtual Machine (JVM) version 1.5 or later -1 Meg free drive space (program only) Recommended software/hardware -Mouse -QRZ callsign database -Internet connection Note: Since this software is written in JAVA, it is able to be run on just about any platform (i.e. PC, UNIX, Mac, etc.). As long as there is a JAVA Virtual Machine available for the platform, this software should run. 3. What is JAVA? JAVA is a programming language designed by Sun Microsystems. JAVA programs are compiled into a binary form that may then be interpreted by a JAVA Virtual Machine (JVM). JAVA Virtual Machines are available for most platforms. In this way, JAVA programs become portable to any JAVA environment. A JAVA Virtual Machine for MS Windows platforms is included in the JAVA Runtime Environment (JRE) that can be freely downloaded from http://java.sun.com. JRE's for other platforms are also available through this site. The installation instructions must be followed carefully to ensure that the correct PATHs are set. Installation of JAVA varies by platform and is beyond the scope of this document. 4. Overview This software is intended for the mid-February and mid-October School Club Roundup Amateur Radio Contest. One objective of the contest is to get students talking on the radio by exchanging information in a low-pressure situation. Stations participating in the contest must exchange their callsign, signal report, class (individual, club, or school station), and state/Canadian province/country. For official contest rules, please visit http://www.arrl.org/SCR/. The features of this software include: - Full network support so that more than one computer can monitor the progress of the contest. - Dupe (duplicate) checking. - Chat window for talking to other client users connected to the same server. - State/province identification by callsign if the QRZ callsign database or an Internet connection is available. - Country identification by callsign. - Automatic scoring. New features/bug fixes in version 1.42 include: - Package now contains a server, client, and a special program to bring up both the server and client on the same computer. - Fixed a bug that caused an exception when editing a country in the Edit window. - Rewrote QRZ website lookup code to be more robust to ever-changing format of website. - Enhanced automatic school/club identification when DB is used. - Fixed a bug with the "UTC" and "Time since last QSO" displayed in the client. Previously, this display was tied to a client's local clock, so all clients showed a different display if their clocks weren't perfectly synchronized. Now all clients calculate with respect to the server's time and should be within a second or two of each other. Note that this bug did not affect the official timestamps or 30 minute time off intervals in the log; it only made users think a 30 minute time period had elapsed when it had not or vice versa, and was only noticable when the clients and server were not being run on the same computer. - Edit window now includes PSK as one of the modes. - Made the partial callsign matching work correctly. Wasn't updating when using the backspace or delete keys, nor when editing in the middle or beginning of a callsign, etc. New features/bug fixes in version 1.40 include: - The client now loads faster. This is especially noticeable when the log is large. - Added the ability to change the font size/boldness for the information being entered. This is useful when multiple people (talker, logger, control operator, curious bystanders, etc.) need to be able to see the data being entered. - Duplicate callsigns are now looked up QRZ database. (Previously, if a callsign was a dupe, no database lookup was performed.) The fields in the main window are filled in with the data previously logged, while the "Lookup" window displays the data contained in the database. - Added the ability to save/restore the positions and sizes of all the windows. Operating experience has shown that most program users like to tile multiple windows, which can take several minutes to adjust to personal preference. This feature allows each user to quickly restore their window positions each time they move into the logger's seat. - Fixed a bug that caused the "Lookup" window to display "information available" when no QRZ database was in use. Now it displays "No information available". - Added a callsign database lookup using the World Wide Web. - Fixed a handful of database lookup bugs, including incorrect search results, database overruns, etc. - The state field is now automatically filled in with "AK" or "HI" for callsigns with prefixes for Alaska or Hawaii respectively. If the QRZ database indicates a different state, the state found in the database is used instead. - Numbers in the "Scores" window are now right justified. - Updated the list of country callsign prefixes. - Added PSK mode. - Fields are now automatically filled in if a station was worked earlier in a different mode. For example, if a station was worked in a phone mode earlier, the same values (except for the RST) will be automatically copied into the fields when working the station in a digital mode. These values can, of course, always be overridden by the user. New features in version 1.30 include: - A bug with Microsoft operating systems resulted in the file allocation table (FAT) not being updated when a file buffer was flushed. As a result, a power interruption to a computer running Log It! would result in lost data. A work-around has been implemented. - In accordance with a rule change, Canadian provinces now count as multipliers. When contacting a Canadian province, the standard postal abbreviation for the province should be entered in the State field. For countries other than the United States and Canada, the State field should contain the string "DX". - The Statistics window contains a progress bar indicating the amount of time elapsed since the prior QSO. This is handy in determining when to take 30 minute breaks from operating. - The client may now be run in safe mode. Safe mode disables the user from logging QSOs or editing the log. This is useful if a person wishes to monitor the progress of the contest from a remote location without risk of interfering. Chat may still be sent from a client running in safe mode. - The Operators window now includes the amount of time each operator has worked, the percentage of the total contest time, and the average QSO rate for each operator. New features in version 1.20 include: -Statistic window displays QSO rates, TIME ON during the last 24 hours (restriction in the contest rules), and QSO band distribution. -Partial Callsign Match window searches for partial callsign matches already in the log based on the text entered in the main window's callsign textbox. New features in version 1.12 include: -Operators window displays number and percentage of QSOs per operator. -Automatically inserts DX into the State field when callsign is not from the United States. -Notifies user when callsign is from a state/country that is a needed multiplier. -Double clicking on a log entry brings up an Edit window. -Hitting in the Edit window is the same as pressing the Change button. Hitting is the same as pressing the Cancel button. -Multiple Edit windows are no longer allowed. -+ is a shortcut for the Send button in the Chat window. 5. Running Log It! Log It! is designed as a client-server application. The server is responsible for storing the log, performing duplicate checking, providing an official timestamp to log entries, etc. The clients provide a user interface to interact with the server. Multiple clients may be run if, for example, multiple people wish to monitor the progress of the contest (e.g., students located outside of the hamshack elsewhere on campus or even friends and family members who are off campus). Most people will be interested in running the server and client on the same computer. Instructions for doing this are contained in section 5.1. Instructions for running the server and client independently (and thus possible on different computers) are contained in sections 5.2 and 5.3 respectively. 5.1 Running the Server and Client on the Same Computer Note that JAVA is case sensitive. Make sure that the "L" and "I" in "LogIt" are capitalized when typing the following commands. To start the client and server together, from a command prompt change to the directory where you downloaded and uncompressed Log It! There should be a "logit" directory at this level. The format for running Log It! is: logit.LogIt [QRZ database | -web] Where: is the pathname of the log file. is the pathname to a backup copy of the log file. (If possible, and should be on different physical drives to protect the data from a drive crash.) [QRZ database] is the optional pathname to the QRZ database file sorted by callsign. [-web] optional argument indicating Log It! should attempt to use www.qrz.com to lookup callsign info. (Note: If both the [QRZ database] and [-web] options are passed, lookups will be performed via the QRZ database only.) For example to keep a log file on the hard drive at "c:\contest\KC7MOD.LOG", a backup copy on floppy at "a:\KC7MOD.BAK", and incorporate the QRZ database at "d:\callbk\callbkc.dat" type: java logit.LogIt c:\contest\KC7MOD.LOG a:\KC7MOD.BAK d:\callbk\callbkc.dat Or, to do the same, but not use the QRZ database type: java logit.LogIt c:\contest\KC7MOD.LOG a:\KC7MOD.BAK Or, to do the same, but use the web lookup instead: java logit.LogIt c:\contest\KC7MOD.LOG a:\KC7MOD.BAK -web [Note: It is preferable to buy the QRZ database rather than just use the web lookup. The web is dynamic, and therefore the web lookup may break at any time. The database on CD produces much faster lookup times and hopefully will be more reliable. The price of the CD helps to support the nice people at QRZ, especially AA7BQ, who generously donated some of the code for database lookups to this software. (And hey! The software itself is free, so there really isn't too much to complain about!)] If everything is OK, the following is displayed: Log It! version 1.42 radtken@aztecfreenet.org (KC7MOD) Server running... ClientManager running... If you receive the following error: Exception in thread "main" java.lang.NoClassDefFoundError: ... chances are you either mistyped the command (pay attention to capitalization) or executed the command in the wrong directory (make sure a directory listing shows the "logit" directory). Exiting Log It! will cause both the client and server to terminate. After being interrupted, Log It! may be restarted in the same way it was originally started. The log files are automatically validated and resynchronized, even if only one still exists. Clients still connected at the time of a server interruption must be restarted. When running the server and client together on the same machine, it is still possible for additional clients to connect. See section 5.3 for instructions on running additional clients. 5.2 Running the Server Note that JAVA is case sensitive. Make sure that the "S" in "Server" is capitalized when typing the following commands. To start the server, from a command prompt change to the directory where you downloaded and uncompressed Log It! There should be a "logit" directory at this level. The format for running the server is: logit.server.Server [QRZ database | -web] Where: is the pathname of the log file. is the pathname to a backup copy of the log file. (If possible, and should be on different physical drives to protect the data from a drive crash.) [QRZ database] is the optional pathname to the QRZ database file sorted by callsign. [-web] optional argument indicating Log It! should attempt to use www.qrz.com to lookup callsign info. (Note: If both the [QRZ database] and [-web] options are passed, lookups will be performed via the QRZ database only.) For example to keep a log file on the hard drive at "c:\contest\KC7MOD.LOG", a backup copy on floppy at "a:\KC7MOD.BAK", and incorporate the QRZ database at "d:\callbk\callbkc.dat" type: java logit.server.Server c:\contest\KC7MOD.LOG a:\KC7MOD.BAK d:\callbk\callbkc.dat Or, to do the same, but not use the QRZ database type: java logit.server.Server c:\contest\KC7MOD.LOG a:\KC7MOD.BAK Or, to do the same, but use the web lookup instead: java logit.server.Server c:\contest\KC7MOD.LOG a:\KC7MOD.BAK -web [Note: It is preferable to buy the QRZ database rather than just use the web lookup. The web is dynamic, and therefore the web lookup may break at any time. The database on CD produces much faster lookup times and hopefully will be more reliable. The price of the CD helps to support the nice people at QRZ, especially AA7BQ, who generously donated some of the code for database lookups to this software. (And hey! The software itself is free, so there really isn't too much to complain about!)] If everything is OK, the following is displayed: Log It! version 1.42 (server) radtken@aztecfreenet.org (KC7MOD) Server running... If you receive the following error: Exception in thread "main" java.lang.NoClassDefFoundError: ... chances are you either mistyped the command (pay attention to capitalization) or executed the command in the wrong directory (make sure a directory listing shows the "logit" directory). There is no specific provision to stop the server. On MS Windows or UNIX platforms, the server may be stopped by entering +C. After being interrupted, the server may be restarted in the same way it was originally started. The log files are automatically validated and resynchronized, even if only one still exists. Clients still connected at the time of a server interruption must be restarted. 5.3 Running the Client Note that JAVA is case sensitive. Make sure that the "C" in "Client" is capitalized when typing the following commands. Once the server is up and running, the client may be started. To start the client, from a command prompt change to the directory where you downloaded and uncompressed Log It! There should be a "logit" directory at this level. The format for running the client is: java.client.Client [-s] Where: is the name of the JAVA Virtual Machine (probably "java"). is the actual hostname or IP address of the server machine. If the client is run on the same machine as the server, "127.0.0.1" or "localhost" may be used. [-s] optional flag indicating the client should be run in safe mode. In safe mode, the client is unable to submit information to the log. The ability to edit existing log entries is also disabled. The Client should be run in safe mode when a person only wishes to monitor the progress of the contest. For example, to run the client on a machine already running the server type: java logit.client.Client 127.0.0.1 Or, to run the client but use the server on a remote machine at 192.168.0.4 type: java Client 192.168.0.4 Note: Multiple copies of the client may be run on multiple machines. Once a client is launched and it makes a successful connection to the server, a window will pop up. If you receive the following error: Exception in thread "main" java.lang.NoClassDefFoundError: ... chances are you either mistyped the command (pay attention to capitalization) or executed the command in the wrong directory (make sure a directory listing shows the "logit" directory). If you receive the following error: Client class exception: java.net.ConnectException: Connection refused then there was a problem connecting to the server. Double check that the server is running, you correctly typed the hostname/IP address, and that both the server and client machines are connected to the network. Clients may be stopped (File pull down menu) and re-started at any time. When a client is terminated the server remains running. 6. Using the Program When a copy of the client is run, the main window titled "Log It!" appears. The cursor starts in the textfield labeled "Callsign". When a callsign is entered in this textfield followed by a , the cursor automatically moves to the textfield labeled "RST". If a QRZ database or web lookup is being used by the server and the callsign exists, the textfield labeled "State" is filled in. Also, if the QRZ database reports the callsign to be either a club or a school, the "Class" field is updated and a message is displayed at the bottom of the window. Finally, the textfield named "Country" is initialized with the correct country. If the callsign is a duplicate already contained in the log, the program will display a warning message. If this is not the case and all the information is correct, or the "Log It" button may be pressed to log the data. Otherwise, may be used to navigate through the "RST", "Class", "State", and "Callsign" fields. The mouse or will move the focus through the remaining menus, textfields, and listboxes. Note that after entering a callsign in the callsign textfield and hitting , the program will not perform a QRZ database or web lookup, nor will it fill in the country textfield. In order to use this feature, must be pressed instead. Every time the "Log it" button is pushed, or the key pressed, all the information is logged. Each new state or country is marked with an asterisk in the log. The "State" field should contain the standard postal abbreviations for United States and Canadian callsigns. For all other countries, the string "DX" should be entered. A warning is displayed for duplicate callsign entries. Please be sure that the "Operator" field is supplied and that the band and mode are correct. A log entry may be corrected by selecting it and clicking the "Edit" button, or double clicking on the entry in the list. Changes may then be made in the edit window and accepted with the "Change" button, or rejected with the "Cancel" button. Every time 30 minutes elapses without a contact, a blank line is appended to the log. This represents a "TIME OFF" and is not calculated into the elapsed time. The "File" pull down menu contains three options: "Load window positions..." and "Save window positions..." allow a user to quickly save and restore the positions and sizes of all windows. Since most users have a personal preference as to the arrangement of the software's windows, this allows each user to quickly switch to his or her layout. The final option under the "File" pull down menu is "Exit", which causes the client to terminate. The "Edit" pull down menu contains the "Clear Fields" option which may be selected to reset the fields on the bottom of the main window. The "Callsign", "State", and "Country" fields are cleared, "RST" is reset to either "59" or "599", and the "Class" is reset to "I". The "Edit" pull down menu also contains the "Font size" option, allowing the user to change the size and boldness of the font used for the fields on the bottom of the main window. This is useful when multiple people (say a talker and a logger) need to all read the screen. The "Window" pull down menu presents seven choices. "Contacts" brings up a summary of state, province, and country QSO's. "Score" reports the current score. "Lookup" displays the name, class of license, and address of the last callsign entered in the "Callsign" field of the main window if the QRZ Database or web lookup is being used. The "Operators" window displays the name of the operators along with the number and percentage of QSOs obtained during the contest. It also contains the amount of time each operator has worked, the percentage of the contest elapsed time this represents, and the average QSO rate. (NOTE: Operators are extracted from the names entered in the Operator textfield in the main window.) Other windows include "Chat", "Rates and Statistics", and "Partial Callsign Match". The "Chat" window may be used to communicate with other clients. It contains a conversation log, a list of client operators, and a box to enter new text. Clicking the "send" button will broadcast the entered text to all attached clients. When chat is received, it is added to the conversation log and displayed at the bottom of the main window. An audio alert is also sounded. The key remains active and may be used to navigate through the various controls. The chat text is also logged to the file "chat.txt". The "Rates and Statistics" window contains two panels. The first panel displays the current rate of QSOs based on the last 20 and 60 minute intervals. It also displays the average rate for the entire period operated during the contest. Next, the first panel displays the TIME ON (i.e. time operated) during the last 24 hours. This is useful because the official rules prohibit operating more than six hours in a 24 hour period. Finally, the first panel contains a progress bar indicating the amount of elapsed time since the prior QSO. This is useful for deciding when to take a 30 minute break. The second panel of this window simply displays the number of QSOs per band. The "Partial Callsign Match" window helps accelerate the "hunt and pounce" method of contest operating. When a character is entered in the callsign textfield in the main window, the "Partial Callsign Match" window immediately searches through the contest log, looking for callsigns that contain the pattern in the textfield. It then displays up to 50 matches. For example, if the pattern "MO" were entered in callsign textfield, the "Partial Callsign Match" might display the callsigns "KC7MOD" and "KC7MOC", assuming both these stations were already in the log. It would not find "WA7ZPU", since this callsign does not contain the pattern "MO". 7. Troubleshooting There is some variation among JVM's that may cause this program to run differently depending on what JVM is being used. These variations seem to occur both across platforms (e.g., JVM's for Windows versus Macs) and across versions of a JVM for a single platform. I've attempted to address some of these inconsistencies when possible. However, I spend the majority of time testing using Sun's JVM under Linux. If you find something does not work as expected, try using a different version of a JVM, a different company's JVM, or a JVM on a completely different platform. If the behaviors are inconsistent between the two scenarios, please let me know so I can investigate a workaround. Please report any bugs and send suggestions, comments, etc. to: KC7MOD Nicholas Radtke radtken@aztecfreenet.org This software is available for download at: http://www.asu.edu/clubs/amateur_radio_society Happy contesting!