Note that this section is written from the point-of-view of a player-side author who wants to read the file. Information for host-side authors is below.
The file is stored in DOS format. That is, all multi-byte values are in little-endian, two's complement format. The following data types are used:
| byte | a 8-bit byte (0..255) |
| char | a 8-bit ASCII character |
| word | a 16-bit word (-32768..32767) |
| long | a 32-bit word (-2147483648..2147483647) |
| type[NN] | an array of type, usually indexed 1-based |
Each utilX.dat consists of a number of records. Each record starts with a header of the following form:
word Record Type word Record Size
The Record Type tells you what the record contains. The header is followed by the record contents which has the length as specified in Record Size. All types defined by PHost are described below.
The maximum size of a record including its header is 32k, to avoid trouble with programs that interpret the Record Size as signed (programming languages like Java or BASIC have no unsigned types).
Strings are generally stored in BASIC format, that is, they are padded to their field size with spaces. ► Note: Since PHost lives in a C world, some versions erroneously write out C strings (terminated with a null byte), and some add-on programs also do that. You should therefore accept both formats. Read the file format list for general advice.
There is no general convention about the extended character set used in strings (other than 7-bit ASCII). It seems that the most common extended character sets are DOS codepages, not ISO Latin or Windows codepages. This problem mostly applies to ship and race names.
► Note: Utilities should dynamically read and use the Record Size field to determine how many extra bytes to read after the header, rather than using pre-computed values from sizing the data structures below. This allows utilities to not necessarily know about or respond to certain record types (if more record types are added after the utility has been released), and to correctly ignore additional fields that may be added to existing records. Some records may also be shorter than described here when an older PHost version is used. Version dependencies, if known, are documented here.
► Note: Record Size may be 0, indicating that the next record's header follows immediately, without any data for the current record.
The order of the records generally follows the host sequence, so if an item is reported several times, the most current information comes last. Note that the record numbers have no relation to the ordering in the file.
Every utilX.dat file starts with a control record.
