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:
<FORM METHOD="POST" ACTION="ImportADIF.cfm" ENCTYPE="multipart/form-data">
File to Upload: <INPUT TYPE="FILE" NAME="Filename">
<INPUT TYPE=SUBMIT VALUE="Upload It">
</FORM>
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: <EQSL_USER:6>WB4WXX <EQSL_PSWD:4>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:
<!-- Reply form eQSL.cc ADIF Real-time Interface -->
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 <BR> 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
