The TIFILES format is used to encode files from a TI file system for transfer and storage on another system. Most other systems do not know specific file formats. For example, Unix and Windows systems handle all kinds of data files in the same way, leaving the processing up to the application.
If you were to take a file and send it over to a PC or some other computer via a modem or serial cable it would arrive on the other end but lose some information. It would lose information like what kind of file it is, protection status, how large it is, etc. In order not to lose that information, proper communication programs on the TI prepend (stick on the front) a 128 byte header to the file that captures this information. So now when the file arrives on the other computer it is actaully a little bit larger.
When the 128 byte header is prepended to the file it becomes a "TIFILES". So by definition, a TIFILES file is a regular file with a 128 byte header. Now if you were to send that same program back to the TI, the 128 byte header gets read so the file is created properly on the TI. Of course, the 128 byte header is removed when it is back on the TI. The 128 byte header is small set of information used to properly rebuild the file once sent back to the TI. If you send a NON-TIFILES file (one without the 128 byte header) to the TI it will get built but more than likely it won't work properly.
Thus, when files shall be stored on a PC and probably later copied to another TI system, the file format information must be preserved. When the file is downloaded to a TI or Geneve (e.g. using the TELCO program), the file may be reconstructed in its original format.
File name conventions
Currently there is no real agreement on file names. In most cases, files that are stored in TIFILES format have a suffix like ".ARC" or ".ARK" to indicate that they were packed with Archiver. This has nothing to do with TIFILES, but most external files are packages anyway, and there is no other format for exporting but TIFILES.
However, with the increasing use of PC software like emulators, there should be a convention to properly indicate the format. One suggestion is that files containing data in TIFILES format should have the extension tifile, tifiles, or tfi. The file name may be equal to the TI file name, lowercase or uppercase, or give an indication how to process the file on the TI system, like applying a dearchiving program.
Examples: assm1.tifile, MyLetter.tifile, EDIT1.tifile, telco.arc3.tfi.
The TIFILES format consists of a header and a body. The header is 128 bytes long and contains the file format information. The body contains the file contents as a sequence of the contents of those sectors that the file occupies on the TI file system. The file length is a multiple of the sector length (256) plus the 128 bytes header.
|0x08||Total number of sectors||Flags||#Rec/sect||EOF offset||Rec length||#Level 3 records|
|0x10||File name (first 8 bytes), padded with spaces|
|0x18||File name (last two bytes)||MXT||reserved||Extended header||Creation time|
|0x20||Creation time||Update time||Unused|
The fields in the TIFILES header have the following meaning.
The Flags field
The Modified bit is set to one when a write operation occurs on this file (not with all DSRs). It may be reset by backup programs.
DIS/VAR files have a 0x80 (plain), 0x90 (mod), 0x88 (prot), or 0x98 (mod/prot) value. Program files have 0x01 (0x11, 0x09, 0x19).
Total number of sectors and EOF offset
The EOF offset is the location in the last sector where we find the EOF marker. Only variable length data files have an EOF marker (0xff). For program files and fixed length files this field points to the first byte after the file contents. If the EOF offset contains 0, the last sector is completely filled with data.
The length of the complete TIFILE-encoded file is always a multiple of 128. To recreate the actual file length,
- the total number of sectors must be multiplied by 256
- the number of bytes past the EOF marker must be subtracted (if the offset is not 0).
That is, if the number of sectors is 10 and the EOF offset is 36, the file length is (10*256) - (256-36) = 2340. If the EOF offset is zero, we get the full 2560 bytes.
NOTE: The bytes in this field are in reverse order (little-endian).
In the case of fixed length records, the field "Number of Level-3 records" contains the highest record actually written to. If the last sector is filled as far as possible, we have
- L3 = Records/Sector * Total number of sectors
This number is required to determine the highest record number, especially if the last sector is not filled completely.
In the case of variable length records, it contains the highest sector actually written to and should therefore be equal to the field "Total number of sectors".
For program files, 0x0000 is usually found in this field.
The high byte of the record count as used in the SCSI software specification is not included in the TIFILES header. This byte is required for large files with more than 65535 records; thus, the TIFILES format does not support files with such a very large number of records.
The creation and update time specification are two 16-bit words, the bits having the following meaning:
With only 5 bits for seconds, the timestamp has a resolution of 2 seconds. The years reach from 1970 (values 70..99) to 2069 (values 0..69).
The MXT flag is used for chains of files; 0 means last file.
The extended header field, set to 0xffff, indicates that there are additional fields in the header; currently, there are the creation and update time. Otherwise this field contains 0x0000.
The unused part until 0x7f is padded with spaces (0x20), but has also been seen padded with other bytes. TELCO fills these bytes up to 0x7f with 0xca53.
- No filename: Some programs like TELCO create incomplete TIFILES headers, omitting everything starting at byte 0x10 (filename). In that case, the filename must be manually set, especially when transferring to a TI-99 system.
- Multiple files: The first byte may be set to 0x08 for multi-file transfer using MXT YModem. Single files should only have 0x07 as the first byte. In that case, the MXT field is set to 0 if this is the last file in the file sequence, and non-null if there are more files.
- File length: The file may show a total length which is not 128 plus a multiple of 256. In that case, the last sector is incomplete and assumed to be padded with zeros.