Log It! Version 1.42a 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/school-club-roundup . 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.42a include: - Log entries may be deleted by right clicking on an entry and selecting "Delete" or by highlighting an entry and pressing the key. - Added the ability to log both the RST sent and comments. - Chat text is now time stamped. - Expanded the callsign field in the log from 9 to 15 characters. 9 was too short as it truncated calls like AB0CDE/FG1 or AB0CDE/QRP. 15 characters should accomodate almost all callsigns. - Widened the mode field in the log to 8 characters. This is the maximum width used by the current ADIF specification for modes. - Added Olivia, Hell, and MFSK to the list of modes. 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 client provides 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 possibly 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 Log It! was downloaded and uncompressed. 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.42a 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). When running the server and client together as described in this section, 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 Log It! was downloaded and uncompressed. 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.42a (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 Log It! was downloaded and uncompressed. 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 logit.client.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 (by selecting "Exit" from the "File" menu) and re-started at anytime. When a client is terminated the server remains running. 6. Using the Program In the main window, fields exist for logging the following information: Required fields: -Callsign -RST received -RST sent -Class ("I" for independent, "C" for club, "S" for school) -State/province (Set to 2 letter USA state or Canadian province abbreviation; Set to "DX" for non USA/Canadian QSOs) -Country -Mode -Band Optional fields: -Operator -Comments There are two keyboard methods for moving from field to field: 1) Using to navigate between fields is the preferred method. When using to navigate between fields, the cursor will only stop in the following fields in the following order: Callsign -> RST -> Class -> State -> RST Sent -> Callsign In addition, pressing in the "Callsign" field causes Log It! to automatically fill in the "Country" field and possibly the "State" field if it can be determined by the callsign. If Log It! is being used in conjunction with the QRZ database or web lookup, the "Class", "State", and "Country" fields will be updated based on the information, if any, retrieved from the database. If Log It! believes the station being worked is a club or school, a message appears across the bottom of the main window along with an audible beep, reminding the user to confirm the class of the station. Likewise, if Log It! believes the station's state or country is a multiplier, a message appears across the bottom of the main window accompanied by a beep. In addition, pressing in the "Callsign" field performs a duplicate check. If a callsign has already been logged in the same mode (either phone or digital), the word "DUPE:" followed by the duplicate log entry is displayed in red across the bottom of the main window, accompanied by an audible beep to warn the user. If a callsign has already been logged in a different mode (i.e., log entry is a digital mode but current mode is set to a phone mode) then Log It! fills in all the appropriate fields based on the previous QSO with the station. 2) may be used to navigate from field to field as well. The main differences when using instead of are: - stops in all fields. -When using : *no fields are automatically filled in. *the QRZ database is not queried. *no multiplier checks are performed. *no duplicate checking is performed. In general, should normally be used to navigate except for in unusual situations, such as where the information in the database is wrong, a field has been manually overriden, access to a field does not stop in is required, etc. A mouse may also be used to navigate. As with , no fields are filled in, duplicate checking performed, etc. when navigating with a mouse. The up and down arrows may be used as a shortcut to quickly navigate between the "RST" and "RST Sent" fields. To log a QSO, may be pressed while any of the following textfields have focus: "Callsign", "RST", "Class", "State", "Country", "RST Sent", or "Comments". In addition, the "Log it" button may be pressed. Log It! performs duplicate checking on the callsign and error checking on the fields and displays a warning dialog if data appears to be erroneous and/or missing. Selecting "No" will cancel logging the QSO and allow the erroneous data to be corrected. Selecting "Yes" will log the QSO despite possible errors. After a contact is logged, the elapsed time is updated by adding the amount of time that has elapsed since the previous QSO was logged. If more than 30 minutes has elapsed since the previous QSO, it is considered a time off break and no time is added to the elapsed time. When a QSO is logged after a 30 minute or longer break, a "TIME OFF" record is added to the log to denote the break. When working American or Canadian stations the "State" field should be filled in with the standard two letter postal abbreviations for states or provinces respectively. For all other DXCC entities, the characters "DX" should be entered. Each new state or country is marked with an asterisk in the log. A log entry may be corrected by selecting it and clicking the "Edit" button, double clicking on the entry in the list, or selecting it and then right clicking and selecting "Edit" from the popup menu. Changes may then be made in the edit window and accepted with the "Change" button, or rejected with the "Cancel" button. A log entry may be deleted by highlighting the entry and then either pressing or right clicking and selecting "Delete" from the popup menu. A dialog will appear confirming that the entry should be deleted. The "File" pull down menu contains three options: "Save window positions..." and "Load window positions..." allow a user to quickly save and restore the positions and sizes of all windows. Since users may 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" and "Sent RST" are 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 "Options" pull down menu contains two options. If "Remember previous RST Sent field" is set, the "RST Sent" field is not reset when a QSO is logged or when clearing all fields. This is useful if the signal report being sent is the same for most stations but below 59 or 599. If unselected, the "RST Sent" field is reset to 59 or 599 after each QSO or when the fields are cleared. Whether or not stops in the "RST Sent" field can be controlled by toggling the " stops in RST Sent field" option. Depending on how frequently the RST sent is changing, it may be convenient to turn this option on or off. The "Window" pull down menu presents seven choices, described below: The "Contacts" window contains a summary of state, province, and country QSOs. The "Score" window reports the current score. The "Lookup" window displays information retrieved from the QRZ database or web if available, including the name and address, of the last callsign entered in the "Callsign" field of the main window. The lookup is performed by pressing while the cursor is in the "Callsign" field. No lookup will be performed if is pressed instead. 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. For this information to be accurate, the "Operator" field should be filled in whenever operating. If a QSO is logged without an operator or with the incorrect operator, the error may corrected by editing the log entry. 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 in the "Chat" window and may be used to navigate through the various controls. The chat text is also logged to the file "chat.txt" in the directory from which the server was run. 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 time elapsed 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!