File headers and formats of Sinclair QL QDOS executable files

Question

The Sinclair QL operating system QDOS has filetype metadata stored in a "header" in the filesystem separate from the files. I can find most but not all of this header. Here's one:

00 00 01 a4              ddw       1A4h              file length
00                       db        0h                access key (unimplemented)
01                       db        1h                file type: 1 = exe
00 00 10 00              ddw       1000h             when exe: data area size
00 00 00 00              ddw       0h                ????
00 0f 50 44 5f 33 36 5f  p_string  "PD_36_NoEsc_exe" filename
4e 6f 45 73 63 5f 65 78                              "
65                                                   "
00 00 00 00 00 00 00 00  ??[21]                      more space for name
00 00 00 00 00 00 00 00                              "
00 00 00 00 00                                       "
4f 47 75 4b              ddw       4F47754Bh         update date
00 02 13 29              ddw       21329h            reference date
00 00 00 00              ddw       0h                backup date

The 'file type' field is '0' for most files, '1' for executables, '2' for 'relocatable files', which might not have been implemented?, or '255' for directories.
The next eight bytes serve different purposes depending on the 'file type' field. So far the only further details I can find is that in the case of executable files, the first four bytes are a 32-bit 'data area size' which is essential for running executables on the QL.

But I can't find whether the last four bytes have any meaning for executables, or what purposes these eight bytes serve for an 'file type' other than executables.

Then in the executable file itself there is also a tiny header, here's two examples:

00000000 dd cc                    adda.l      A4,A6
00000002 38 1f                    move.w      (SP)+,D4w
00000004 60 0a                    bra.b       LAB_00000010
00000006 4a fb                    dw          4AFBh
00000008 00 05 4e 6f 45 73 63     p_string    "NoEsc"
0000000f 00                       ??          00h
                 LAB_00000010
00000010 55 44                    subq.w      #0x2,D4w

00000000 60 00 00 82              bra.w       LAB_00000084
00000004 00 00                    ????        0000h
00000006 4a fb                    ddw         4AFBh
00000008 00 08 08 61 6e 61 63     p_string255 "anaclock"
         6c 6f 63 6b

So it seems that code execution always starts at offset 00 but that there's a 16-bit magic word/signature 0x4afb at offset 04 followed by a Pascal string with a 16-bit length field which is the name of the program. The first four bytes always contain logic to skip past the header and continue execution.

But so far I can't confirm this and haven't been able to find it documented. Is it always the same? Can the signature field hold values other than 0x4afb?

So I'm looking for the full definition of the 8 type-dependent bytes in the header and confirmation of my guesswork in the format of the executable file.

Answer 1

The QL operating system sets aside 64 bytes per file for metadata purposes. Not a lot of them has traditionally been used and you have already found most of the uses. The "most modern" format of the file header is shown below (dates and version numbers are only used in newer versions of QDOS)

$00 long        file length
$04 byte        file access key 
$05 byte        file type
$06 8 bytes     file type-dependent information
$0E 2+36 bytes  file name
$34 long        update date
$38 word        version number 
$3A word        reserved
$3C long        backup date

As you correctly write, file type 0 is a "normal" file, 1 an executable program, and 2 a relocatable (Sinclair SROFF format) object file (and 2 is actually in use, quite a number of assemblers create files of this type). File type 255 is used for directories in device drivers that support them.

The "file type-dependent information" is not restricted in any ways by the OS - If an application wants to implement specific data in here (in its "private" file type space), it is free to do so (and some did). The OS itself basically only uses the 4 bytes you mentioned that give the stack and data size for an executable job.

In case you come across an application suite named ProWess, these are known to set their own file types and make use of their own metadata.

With regards to the start of an executable file, what you found is just a marker to mark the displayable job name (once the job is executing) that can be shown by some tools when you ask for a list of tasks. An executable file is expected to look like that:

      bra   JOB_START 
      dc.w  0
      dc.w  $4AFB
      dc.w. ne-* 
      dc.b  'Job name'
ne: 
      dc.w  0

JOB_START
* Code begins execution here (assuming that the start address
* defined when the job was created was zero)

The tools simply identify if the job has a "proper" header with the mark in the proper place and then assume the string as valid and pick pick it for display.

When an executable file does not provide this "standard header", the system will still run it properly (provided everything else is to spec), but the tooling will just not display a name.

$4afb (an illegal instruction) is used in many places in QDOS as a header marker.