TIFILES format

From Ninerpedia
Revision as of 21:02, 28 March 2019 by Mizapf (talk | contribs) (→‎Format deviations)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Overview

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

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.

TIImageTool uses ".tfi" as a default suffix.

The Classic99 emulator uses the TIFILES format to access files and makes use of the PC file name. Accordingly, it does not make use of a specific file name suffix.

File structure

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.

0 1 2 3 4 5 6 7
0x00 0x07 T I F I L E S
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
0x28 Unused
...
0x78
0x80 Content
...
n

Fields

The fields in the TIFILES header have the following meaning.

The Flags field

MSB LSB
0 FIXED Reserved normal Unmodified Unprotected Reserved DISPLAY Data
1 VARIABLE Emulate File Modified Protected INTERNAL Program

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.

Level-3 records

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.

Time specifications

The creation and update time specification are two 16-bit words, the bits having the following meaning:

hhhh.hmmm.mmms.ssss 
yyyy.yyyM.MMMd.dddd 

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).

Other fields

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.

Format variants

  • 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. The Classic99 emulator uses the PC file name, not the name in the file name field.
  • 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.