EQSL.CC REAL-TIME LOGGING SOFTWARE INTERFACE revised 19 July 2012 Any questions or problems may be directed to Dave Morris, N5UP, E-mail to N5UP@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. You can transmit the data as an HTTP POST, or with the data in the URL: 1. AS AN HTTP POST Logging software can upload one or more QSOs through the ImportADIF.cfm page using an HTTP POST and can retrieve and analyze the results page very simply. The URL is case-insensitive and is: http://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 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 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: http://www.eqsl.cc/qslcard/importADIF.cfm?ADIFData=Test%20upload%20%3CADIF%5FVER%3A4%3E1%2E00%20 %3CEQSL%5FUSER%3A8%3ETEST%2DSWL%20%3CEQSL%5FPSWD%3A8%3ETESTPSWD%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. 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" ERROR MESSAGES THAT ARE FATAL AND INDICATE A BUG IN THE CALLING PROGRAM "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 MAY NOT BE SIGNIFICANT BUT SHOULD BE INVESTIGATED "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: Testpswd (Password is case-sensitive) An example of a FORM can be found at http://www.eqsl.cc/qslcard/testADIF.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: http://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