The Application DOR

Owned by Gunther Strube
Last updated: Apr 25, 2024 by pattersVersion comment

The application DOR(s) may now be placed wherever is convenient (the contain relative data structure pointers), and if there is more than one, chained together via the brother links. An application DOR contains various information relevant to running the application, and may also contain pointers to menu topic help information. The format of an application DOR is as follows:

3 bytes0 0 0Extended pointer to parent
3 bytesx x xExtended pointer to brother (this will be 0 0 0 if this is the only application on the card or the last in a chain)
3 bytes0 0 0Extended pointer to son
1 byte$83DOR type, application ROM
1 bytexTotal DOR length
1 byte'@'Key to info section
1 bytexLength of info section
2 bytes0 0Reserved for future expansion
1 byte'x'Application key letter, i.e. the letter used in the square sequence to enter the application. If several
applications share a letter, then the first is entered by []x, the next by []Zx, the next by []ZZx, etc. A
maximum of ZZZZ is possible. However, a bug in v3.0 of the operating system doesn't allow for more than []ZZx.
1 bytexcontinuous RAM size required, in 256-byte pages (eg. 32 for 8K). This is relevant only to bad applications. This byte ranges from 1 to 160 (160*256=40K). See the section below on bad applications. Use 0 to make your application the default size, which is 8K on an unexpanded machine and 40K on an expanded one, or if your application is good.
2 bytes0 0This is an estimate of environment overhead, ie. how much memory is needed to save the state of the application each time it is exited. OZ will 'learn' from experience how much is actually required anyway, so this feature is best ignored.
2 bytesx xUnsafe (ie. not preserved over pre-emption) workspace size required in bytes (low byte, high byte).
2 bytesx xSafe (ie. preserved over pre-emption) workspace size required in bytes. These workspaces are allocated from the system half of segment 0, downwards from $1FFD, unsafe workspace at the top. They are used when it is important that the workspace is not bound to awkward segments, but rather remains stable in the logical address space. Note that both safe and unsafe workspace draw from the 2K area of memory from $1800 to $2000. This area is also used for the application stack, mailboxes, and some system stack. Therefore you must make sure that all these demands do not exceed the limited supply of available memory. It is probably advisable to limit safe and unsafe workspace to not much more than a couple of pages at the most.
2 bytesx xEntry point for application code (16bit local address). Must be in segment 3. Remember low byte, high byte order.
1 bytexDesired binding of Segment 0 on entry.
1 bytexDesired binding of Segment 1 on entry.
1 bytexDesired binding of Segment 2 on entry.
1 bytexDesired binding of Segment 3 on entry.

Usually you will want to bind the bank containing the code for your application to segment 3 and probably set the other banks to zero. If the application is a bad one, then certain segments will be bound to RAM on entry, depending on the size of continuous RAM selected. The desired binding of such segments must be set to zero to avoid conflict (RAM is paged in after application is created therefore overriding explicit bank references).
1 bytex

Application type byte 1. Set it to a combination of the following bits. Note the bits are not all orthogonal, eg. if 4 is set 8 must be too.

AT_GOOD=1Good application
AT_BAD=2Bad application
AT_UGLY=4Ugly application, bad popdown
AT_POPD=8Popdown, kill on pre-emption
AT_ONES=16 Only one instantiation is allowed (e.g. Diary).
AT_DRAW=32OZ should attempt to preserve screen over pre-emption (ranging from right edge of topic window to left edge of OZ window). This should not be set unless absolutely necessary, ie. when the application cannot reasonably redraw its own screen in response to an RC_DRAW return. Programmer laziness is not sufficient grounds! Note that when memory is low OZ will fail to preserve the screen anyway and will return RC_DRAW after screen corruption.
AT_FILM=64File manager ID, used by the Filer, DO NOT SET.
AT_BOOT=128Application auto-boot, used by the Index, DO NOT SET.
1 bytex

Application type byte 2. Given by combination of:

AT2_CL=1Set CAPS lock on entry
AT2_ICL=2Set inverted CAPS lock on entry (should not be set without bit 1 set too or the effect is undefined).
AT2_IE=128Ignore error returns - internal use only, DO NOT SET.
1 byte'H'Key to help section
1 bytexLength of help section
3 bytesx x xExtended pointer to topics
3 bytesx x xExtended pointer to commands
3 bytesx x xExtended pointer to application help
3 bytesx x xExtended pointer to token base ($000000 for no token, $FFFFFF for system tokens).


If no menus, help or diamond sequences are required then the above should all point to three zeros. E.g. an extended pointer to the beginning of the current application DOR would be suitable (it always contains three zeros).
1 byte'N'Key to name section
1 bytexLength of name
x bytes'xxxx',0Null-terminated application name. If this too long then it will look rather odd in the Index. 12 characters is about the maximum sensible length. Screen driver codes is allowed in the name (e.g. bold).
1 byte$FFDOR terminator byte.

web analytics