EQSL.CC REAL-TIME LOGGING SOFTWARE INTERFACE revised 23 February 2020 Any questions or problems may be directed to Dave Morris, N5UP, E-mail to Dave@eqsl.cc SYNOPSIS Users of the eQSL.cc system currently have the ability to upload an entire ADIF format log file and have it deposited into our central database. But as the Internet becomes more ever-present, some logging software authors have expressed an interest in being able to upload a single QSO in real-time into our database. For this purpose, the ImportADIF program was created. HOW TO USE THE "ImportADIF.cfm" PROGRAM This web page is actually an interactive ColdFusion "form" processor that accepts the ADIF formatted log entry for one or more QSOs and stores the information in our database. It returns a response HTML page that is designed to be parsed electronically. The output is human-readable, but is designed to be read by software, so the output is sparse. The data supplied to the program should in all cases be in ADIF-compliant format, using ADIF tags with an optional Header ending in an EOH tag, and each record terminated by an EOR tag. The eQSL Content Specifications and mandatory data can be found here: https://www.eqsl.cc/QSLCard/ADIFContentSpecs.cfm You can transmit the data as an FORM POST, or with the data in the URL: 1. AS A FORM POST Logging software can upload one or more QSOs through the ImportADIF.cfm page using a FORM POST and can retrieve and analyze the results page very simply. The URL is case-insensitive and is: https://www.eQSL.cc/qslcard/ImportADIF.cfm The only FORM FIELD that is required is "Filename", containing the name of the ADIF format log file with a header and one or more QSO line items. Example:
File to Upload:
The eQSL.cc system has username/password security to prevent unauthorized uploading of logs. So, to convey the proper username and password, this information can be stored in one of 2 ways: a. In the HEADER of the ADIF file This method uses two ADIF format tags in the HEADER of the file: EQSL_USER EQSL_PSWD These must be ADIF format tags with a colon (:) followed by the length of the data. For example: WB4WXX TEST OR b. As FORM fields This method does not require any change to the ADIF format file, but rather transmits the data using FORM fields called EQSL_USER EQSL_PSWD If using these form fields, do NOT encapsulate them in ADIF style tags! Just supply the raw data in the fields. 2. AS A URL Logging software can also upload one or more QSOs through the ImportADIF.cfm page by calling it with the "ADIFData" supplied as a URL parameter. This should normally be limited to a single QSO, otherwise the length of the URL may be too long. Remember that special characters such as underscores _ brackets <> and colons : should be escaped. Ampersands & and question marks ? have special meaning to our programs and should be escaped when they appear in the data itself. See the example below: https://www.eQSL.cc/qslcard/importADIF.cfm?ADIFData=Test%20upload%20%3CADIF%5FVER%3A4%3E1%2E00%20 %3CEQSL%5FUSER%3A8%3ETEST%2DSWL%20%3CEQSL%5FPSWD%3A9%3Etestpswd1%20%3CEOH%3E%20%3CBAND%3A3%3AC%3E30M%20%2D%20 %3CCALL%3A6%3AC%3EWB4WXX%20%3CMODE%3A3%3AC%3ESSB%20%3CQSO%5FDATE%3A8%3AD%3E20010503%20%3CRST%5FRCVD%3A2%3AC%3E52%20 %3CRST%5FSENT%3A2%3AC%3E59%20%2D%20%3CTIME%5FON%3A6%3AC%3E122500%20%3CEOR%3E As with the FORM technique, you can supply the EQSL_USER and EQSL_PSWD parameters either inside the ADIF header section, or add them onto the end as additional URL parameters, for example: ...%3CRST%5FSENT%3A2%3AC%3E59%20%2D%20%3CTIME%5FON%3A6%3AC%3E122500%20%3CEOR%3E&EQSL_USER=Test%2DSWL&EQSL_PSWD=Testpswd NEW STARTING JUNE 13 2007: If the user has multiple accounts on the eQSL.cc service with the same callsign and password (as do mobile and portable stations or people who have a vacation QTH), it becomes necessary to determine which of these accounts a log record should be uploaded into. This is done by 2 possible methods: 1. The preferred method is to specify an APP_EQSL_QTH_NICKNAME tag at the record level, containing the QTH Nickname of the account as set in the user's eQSL.cc profile, OR 2. by looking at the QSO Date and determining which account has the correct Callsign Start and End Date. This technique is less reliable because there can sometimes be overlaps in accounts even with the same callsign. NEW STARTING DECEMBER 31, 2008: In case of multiple attached accounts, the "core" account is specified by EQSL_USER and EQSL_PSWD by performing a simple SELECT on callsign+password, and accepting the first record that was returned. Previously, it was possible for this to designate an account that had been unsubscribed from eQSL.cc and was not attached to any other accounts. Thus all attempts to upload a record would fail, even if there was a valid account with that same callsign+password. This has been fixed. However, one other failure mode still exists: If a user has multiple accounts with the same callsign+password and different dates, and these are not attached to each other, it may be possible that the upload will still not find the correct account. Users should be advised that any accounts they personally own should always be attached to each other, in order to properly navigate them. NEW STARTING DECEMBER 26, 2019: We are now importing SAT_NAME, limited to 15 characters. Please use standard names so that incoming and outgoing eQSLs will match! If there's a dash in the standard name, use it! Also note that if you supply SAT_MODE, you do not need to supply BAND, as we will find the uplink band and use it. NEW STARTING FEBRUARY 23, 2020: Any Sat_Name will now be looked up against the names in common usage, such as XW-2C or AO7 or CAS-4B, etc. and the NORAD ID for that satellite stored in the database for this log record for more positive identification. IF the Sat_Name is not found, it is NOT fatal to the import, however it will be displayed as a WARNING so the user can correct it if at all possible. Some of our eAwards depend on the Sat_Name being recognized. See our official list at the bottom of the Satellite Information Page https://www.eqsl.cc/QSLCard/SatelliteInfo.cfm RETURN PAGE FORMAT: The returned HTML page can be identified by the comment string near the top of the page: The returned HTML page will contain one or more result strings. The string that indicates a SUCCESSFUL storage of the new record into the database is: "Result: x out of y records added" (where x and y should be equal if all records were accepted) There are other strings that can be parsed from the results page. These are typically delimited by a
line break tag at the end of the message, especially if the message ends in variable length data. Here is a complete list: INFORMATIONAL MESSAGES THAT MAY BE PRESENT IN ADDITION TO RESULTS: "Information: Received xxxxx bytes" A new message was added 09April2004 to recap the newly added record IF and only if a single (1) record was added: "Information: From: xxxxxx To: yyyyyy Date: yyyymmdd Time: hhmm Band: aaa Mode: bbb RST: zzz" Another information message was added 25April2004 to warn that the log file included multiple records, and that those records were uploaded into different accounts, because the user with the callsign specified has registered more than one account with eQSL.cc. The records were matched up with the profile effective/expiration dates for that user, and deposted into the correct account. This does not indicate an error! This message looks like this: "Information: Records were posted to multiple accounts for callsign xxxxxx" ERROR MESSAGES THAT ARE FATAL TO THE RETURNING OF ANY RESULTS: "Error: File not saved" (indicates a rare and unexpected system error) "Error: The system is down until xxxx" (or any other Error: text containing the word "down") (Indicates the system is being rebooted or is down for some period of time for maintenance) (Any such message should be displayed to the user, as it will usually indicate when to try again) "Error: Uploads with empty file extensions are not allowed" (means the user specified an invalid filename) "Error: The form field Filename did not contain a file." (did the user select a file to upload?) Any HTTP Status Code other than "200 OK". For instance 500 or 503 indicate the server is down for maintenance or is being rebooted and the user should test again in a few minutes. ERROR MESSAGES THAT ARE FATAL AND INDICATE A BUG IN THE CALLING PROGRAM "Error: Missing ADIFData parameter" "Error: Missing eQSL_User" "Error: Missing eQSL_Pswd" "Error: No match on eQSL_User/eQSL_Pswd" "Error: No match on eQSL_User/eQSL_Pswd for date yyyymmdd hh:mm" (added 25Apr2004) "Error: Multiple accounts match eQSL_User/eQSL_Pswd for date yyyymmdd hh:mm" (added 25Apr2004) (Note: the errors dealing with username/password and a particular date are due to the new system allowing a user to have multiple accounts with differing dates, i.e. for different QTH, mobile stations, etc. It is however considered invalid to have 2 or more accounts with the same callsign on the same date, as the system cannot then tell where to deposit the log entries.) ERROR MESSAGES THAT ARE FATAL AND STOP PROGRAM EXECUTION AT THAT RECORD (previous records were imported OK): "Error: No match on eQSL_User/eQSL_Pswd for date yyyymmdd hh:mm" (added 25Apr2004) "Error: Multiple accounts match eQSL_User/eQSL_Pswd for date yyyymmdd hh:mm" (added 25Apr2004) (Note: These errors are possible due to the new system implemented in 2004 allowing a user to have multiple accounts with differing dates, i.e. for different QTH, mobile stations, etc. It is however considered invalid to have 2 or more accounts with the same callsign on the same date, as the system cannot then tell where to deposit the log entries. The user needs to correct this situation in MY PROFILE before trying again.) WARNING MESSAGES THAT INDICATE A PROBLEM INSIDE A RECORD, CAUSING IT TO NOT BE IMPORTED "Warning: Bad QSO Date: yyyymmdd" (where yyyymmdd is some date) "Warning: Y=xxxx M=yy D=zz Bad QSO Time: aaaa" (where xxxx is some year, "Warning: Y=xxxx M=yy D=zz Bad Callsign: aaaa" yy is the QSO month "Warning: Y=xxxx M=yy D=zz Bad Mode: aaaa" zz is the QSO day "Warning: Y=xxxx M=yy D=zz Bad Band/Freq: aaaa" and aaaa is the bad data) "Warning: Y=xxxx M=yy D=zz Bad Sat_Mode: aaaa" "Warning: Y=xxxx M=yy D=zz Bad record: Duplicate" "Warning: QSO Date/Time in Future: Y=xxxx M=yy D=zz Time: hhmm Notes: between the D=zz and the word "Bad" there may be other identifying information, such as callsign, band, mode, or anything else that is available at the time. "Bad Callsign" means that NO callsign was found "Bad Band/Freq" could be either the BAND (or FREQ if no band present) was not in the approved list (see ADIF 2 spec) "Bad Sat_Mode" means the satellite mode was not in the approved list (see eQSL.cc ADIF Content Specs) "Bad Mode" means the mode was not in the approved list (see ADIF 2 spec) "Bad Record: Duplicate" may not be a fatal error, as you may have already uploaded this record CAUTIONARY MESSAGES THAT ARE NOT FATAL BUT SHOULD BE INVESTIGATED "Caution: Y=xxxx M=yy D=zz Sat_Name not found: aaaaaaa" (where aaaaaaa is a satellite name not in our database) "Caution: ProgramID or Logger not found" Note: This message means either the ProgramID tag was missing, or your logger was not in our database (contact us if the latter situation exists) TEST PROCEDURE You can test the proper operation of your interface design by using the following data: EQSL_USER: TEST-SWL EQSL_PSWD: Testpswd1 (Password is case-sensitive) An example of a FORM can be found at https://www.eQSL.cc/qslcard/TestImportADIF.cfm although by the time you read this, that test form will have already been used by others, and the test log record will have already been stored in the database, so clicking the submit button will result in a "Bad record: Duplicate" result page being returned. Still it is informative for purposes of testing the interaction, and you are free to view the source code and see what it does. For a true test, you should register your own unique username so you can perform several tests and delete the resulting log entries when you are finished. For details on the specific ADIF tags that are imported using this facility, which of those are mandatory, and which are optional, see: https://www.eQSL.cc/qslcard/ADIFContentSpecs.cfm Note that, as of 13Feb2007, we now import FREQ as an optional field. We do not check to see if BAND and FREQ agree, and if BAND is missing, we use FREQ to establish the BAND. One or the other must be supplied. FUTURE ADDITIONS CONTEMPLATED We may decide to implement a Secure Sockets Layer (SSL) encryption facility to ensure that the username/password information is not intercepted through the Internet. At present, that risk is so low as to be negligible, however, it would be a useful addition. If we implement this in the future, it will likely be done simply by changing the URL of the script from HTTP: to HTTPS: MODIFICATIONS TO THIS DOCUMENT OR TO SPECIFICATIONS 05 May 2001 - Original publication 17 May 2001 - No substantive changes; Improved explanations of some things 22 May 2002 - Notes added to the "Warning" messages Added Caution message Capture ProgramID or other logging software signature and accumulate stats 30 Dec 2002 - Modified to allow ADIFData, EQSL_USER and EQSL_PSWD to be transmitted as URL parameters as an alternative to the FORM PUT, which some languages may not yet support. 09 Apr 2004 - Added new Information message if a single record was added. Message confirms data that was added. 25 Apr 2004 - Added new Information message for multiple accounts; Add new Error messages for overlapping account dates. 28 Nov 2004 - Added support for Satellite Modes and automatic setting of PropMode when satellite mode is detected 18 May 2005 - Added further clarification of the escaping of ampersands and question marks in the data 13 Feb 2007 - Added FREQ as an optional field 14 May 2007 - Expanded on HTTP POST option 13 Jun 2007 - Put APP_EQSL_QTH_NICKNAME into production to narrow down to a single account 31 Dec 2008 - Filter out unsubscribed accounts when selecting the account to upload into 19 Jul 2012 - Test for QSO Date in the future 03 Apr 2018 - Added the Error: System Down type messages 27 Apr 2018 - Added the Error: Missing ADIFData parameter message 26 Dec 2019 - Added SAT_NAME import 27 Dec 2019 - More clarifications and test protocol 29 Dec 2019 - Documented 2 more error messages that can be returned 23 Feb 2020 - Sat_Name looked up and a Caution returned if it is not in our official list