|
Amateur Data Interchange Format 1.0 (ADIF) Specifications Ever since software has become a part of amateur radio, there have been as many data formats as there have been ham radio software programmers. Hams have struggled with converting data among various formats. Several hams have been discussing such a standard via an Internet discussion. In early 1996 KK7A promoted the idea of a standard for exchange of ham data. An internet reflector was set up for discussing such a standard. WF1B and WN4AZY, as publishers of commercial ham radio software, have taken the best suggestions from this discussion and formed a proposal. Ray introduced it at the 1996 Dayton hamvention. Within a year, this proposal has adapted adopted by most software publishers. We wish to thank everyone who has contributed to this effort. ADIF is infinitely extensible--it will never be outgrown. It can handle binary as well as text data. New data elements may be added to this specification without "breaking" older implementations. It may be easily programmed in any language. The data itself is easily read by eye, and may implemented so as to be transferred via Internet without any encoding.
Purpose: Provide a standard interchange independent of operating system or programming language for amateur data that will permit easy and direct transfer of data conforming to the standard between various amateur programs as well awards and contest sponsors.
Data to be Interchanged: The ADIF standard must not be limited to log data. It should incorporate other categories such as awards multiplier lists, packet spot data, contest rules, etc., and must be expandable to incorporate any new type of data that may appear in the future as the hobby grows and changes. However, as of version 1.0, only specifications for log data have been implemented. Anyone wishing to interchange other types of data will still find these specifications helpful. All that is necessary to transfer other types of data is to apply to ADIF a definition of fields and records to be transferred.
ADIF components: ADIF consists of three components: 1. Physical specifications--a specification of how fields and records are stored. 2. Field type definitions--Specification of how a particular type of data is stored. For instance, DATE should be stored with ASCII characters in the format YYYYMMDD. Examples of other possible data types are Numeric, Windows .BMP picture, binary data containing unspecified non-textual data, or freeform text containing multiple lines. 3. Field definitions--a list of data elements (Call, QSO Date, DXCC country, etc.), and a description of valid values. Each field has a name that is from one to ten characters long. The field name may include the characters A-Z, 0-9, and _, but must begin with a letter. (This is for easy transfer with xBase and other popular existing data formats). 4. File definitions--a description of a category of data. For instance, log data is defined as all data resulting from a QSO, including exchanged info plus any data related specifically to a QSO, such as band/mode, comments, traffic exchanged during the QSO, awards tracking info, and contest scoring info. A category will include a list of fields supported by the ADIF standard for each category. Each record in the file will contain one or more of the supported fields. Additional fields that are not part of the ADIF specification for the file may be added by those creating ADIF files. This will permit export of user-defined fields. However, there is of course no guarantee that these undocumented fields will be imported by a program reading ADIF files, or that a chosen name may not be used for another purpose and imported into the wrong field in future ADIF specifications. Therefore, creators of ADIF files are encouraged to cooperate when adding new fields to so as to derive maximum benefit from ADIF.
1. Physical Specifications: Each data field is preceded by a field name and length enclosed in angle brackets. The name and length are separated by a colon. The field name may be in upper, lower, or mixed case. Case is insignificant. For instance, CALL, Call, or call are equivalent. The length specification is ASCII text in display format, and may be of any non-negative value. The data follows the closing angle bracket. For example: <CALL:6>WN4AZY
Records are made up of multiple fields and terminated with <EOR> or <eor> as an end-of-record marker. For example: <call:6>WN4AZY<band:3>20M<mode:4>RTTY<qso_date:8>19960513<time_on:4>1305<eor>
An optional field type indicator may follow the field length, separated by a colon: For example: <qso_date:8:d>19960513
The field type indicator may be in upper, lower, or mixed case. A field type indicator is optional. For instance, the Field Definition for QSO_DATE specifies that the field is always of type Date, so it is not necessary to repeat it here. However, when exporting user-defined fields that are not part of the ADIF specification, a type indicator will assist anyone attempting to import the data. Any number of characters of any value except < may be added after a field’s data or <eor> and before the start of the next field. This is typically carriage returns and/or line-feeds to make the file easier to read in a text viewer. For example: <call:6>WN4AZY<band:3>20M<mode:4>RTTY <call:5>N6MRQ<band:2>2M<mode:2>FM
In this example, a new line is inserted in the middle of each record, and two newlines are inserted at the end of each record. This makes long records easy to read in a text editor. Optional header information may be included before the actual data in the file. To include optional header info, the first character of the file must be something other than <. Any amount of header info of any value except <eoh> may be included. The header info must be terminated with <eoh>. Any number of characters of any value except < may follow <eoh>. The first < after <eoh> is the start of the first field of the first data record in the file. Here is an example:
If the first character of a file is <, it is presumed to be the first field of the first data record. The ADIF version may be included in the header info as follows: <adif_ver:4>1.00 is included as part of the header specification, an importing program can easily determine the ADIF version used to create the file. Note that this must not be at the beginning of the header info, because < as the first character indicates that there is no header. It is important for the programmer importing ADIF data to note that any number of characters of any value may follow the actual data in a field. For example, carriage return/linefeed, or just a line feed. There is nothing in the specifications to prevent an exporter from placing a comment after the actual data. Therefore, after reading a field’s data based on the length specification, the programmer should read and discard characters until the start of a new field (<) or <eor> is encountered. There is no specification for the order in which fields appear. They may appear in any order. Unused fields may be omitted entirely. Therefore, each record will not necessarily have the same fields. The specification does not prohibit a zero-length field, so those writing import programs should allow for this. There is no specification for field length or maximum field length in the Physical Specifications. Unless there is a length specification in the Field Definition, exporters simply export all data in their field. Importers import as much data as their program can accept. Note that while these examples have all been of simple ASCII fields, the specification permits data of any type or length. It could be easily used to transfer pictures or text documents, for instance.
2. Field Type Definitions:
3. Field Definitions:
Band designations:
DXCC country codes: Handling transfer of DXCC(tm) country info has been a common problem due to lack of an official list. The ARRL maintains everyone's DXCC status using numeric codes. We have adopted their codes for ADIF transfer of data. We wish to thank the ARRL for making this list available. NOTE: Since the ARRL assigns the numbers after the country becomes active, we have been unofficially assigning our own numbers. This will become official with ADIF 2.0. Meanwhile, the table lists the ADIF code as well as the ARRL number, when different.
4. File Definitions: A log record is the data resulting from logging one QSO. ADIF does not specify a minimum required set of fields for log data. Although a record should contain at least :
it is permissible to export data with any of these items missing.
ADIF, xBase and other formats As xBase languages and utilities are very popular (perhaps the most popular) for data handling applications, many parties to the ADIF proposal discussion favored using xBase files as the physical specification. However, this standard was not selected, since it is not easily used by those not using an xBase language, and lacks the flexibility and extensibility that ADIF features. However, a de-facto secondary xBase specification exists. Those wishing to use xBase files that will be compatible with each other may simply use ADIF field and record specifications. We encourage development of public-domain utilities being made available that convert ADIF/xBase files as well as other popular data formats such as Lotus 123, Paradox, MS Access, etc.
Usage of ADIF and limitations In order to maintain the integrity of ADIF and public confidence therein, these guidelines must be followed by anyone wishing to support ADIF. ADIF may be freely used by any individual or organization, non-profit or commercial. Anyone claiming "ADIF compatibility" or "ADIF support", or other language with similar meaning, must be able to import and export ADIF data. Of course data import is not necessary or desirable for all programs. For example, in the case of contesting-only packages, the user will probably want to export the contest data for use in a general logger, but not care about importing data. Authors of such packages shall state they provide "ADIF export compatibility" or "ADIF export support", or other language with similar meaning. Writing a logging package that imports ADIF but cannot export ADIF is not within keeping of the spirit and intent of ADIF. Such a package cannot truthfully claim to be ADIF compatible or to support ADIF. Authors of programs that only import must state that they support "ADIF import compatibility" or "ADIF import support", or language with similar meaning. Packages that export and import ADIF may state that they support "ADIF import and export" or a similar phrase. However, any claims of ADIF support without any qualifiers shall mean that the program imports and exports. Export programs shall be written in good faith so that the data will be of maximum usefulness to the user of the data. Products that export data in such a manner that its usefulness is limited, for example by exporting only a few fields or using non-standard formats or names for fields, cannot claim ADIF compatibility. Export programs should include all data in the file to be exported. If an author has fields that are not in the field list of the ADIF specification, he may export the fields by choosing the most obvious field name, and making a reasonable attempt to notify other ADIF supporters--for example via the ADIF mailing list reflector. In time there will probably be an official standards committee that will maintain the field list.
ADIF Mailing List Reflector and Web sites Those with Internet email may participate in the ADIF discussion. A number of amateurs have been discussing the difficulty in transferring QSO data between the various ham radio software packages that are available, and the desirability of having a standard format so that data can be easily transferred between any two programs. This mailing list has been set up to facilitate the formation of such a specification. Any software developer or any ham who wishes to contribute to this discussion is welcome to participate. You may subscribe to these mailing lists by filling out a form at the ADIF web page (http://www.hosenose.com/adif). This web site also contains links to other publishers who support ADIF. For any questions about this specification, contact us!
Ray Ortgiesen, WF1B 401-823-RTTY Publisher of the popular WF1B RTTY contesting program.
Dennis Hevener, WN4AZY 770-307-1511 Makers of LOGic ham radio software, SARtek universal antenna rotator interface, and other products for the computer in the shack. 14-Jan-2004 http://hosenose.com/adif/adif.html |