DOR's
- Gunther Strube
- Elpekos
DOR may be thought of as standing for "Directory Object Record" - although DOR was not intended as an acronym for this, this does provide quite a good explanation. DORs are a fairly general record structure well suited to displaying hierarchically organized information. They are used in the RAM filening system, but unfortunately not in the EPROM filing system, and in application definitions. Some degree of understanding of them is necessary to extract certain information, such as last updated dates, from the filing system.
Format
A DOR starts with the three link pointers which point to the parent, brother and child respectively. The links are of the form of a 2 byte offset within a bank followed by a bank number, ie. an extended address. If relatives do not exist then the link pointers are set to 0 (three zeroes). The remainder of the DOR consists of a series of keyed subrecords.
3 bytes Link to parent, three zeroes indicates a null (pointer) link
3 bytes Link to brother, three zeroes indicates a null (pointer) link
3 bytes Link to son, three zeroes indicates a null (pointer) link
1 byte DOR type, eg. DM_ROM
1 byte Length of DOR in bytes
1 byte Record key. This is usually a mnemonic, eg. DT_NAM
1 byte Length of record entry in bytes
n bytes Data specific to record (type)
...
... More record entries (in the same form as above)
...
1 byte The DOR terminator, $FF
The above format may be useful if you want to set up a static DOR structure. For example the header for application cards, and the headers for the internal applications, use a static DOR structure. On the whole, however, the internal arrangement of the DOR is transparent to the user and the DOR interface can be used throughout. This interface works with the following types and record keys:
NOTE: In the following descriptions the ASCII character corresponding to a hexadecimal value is sometimes placed next to it within brackets. This is done to indicate the mnemonic nature of the values used. For example ($4E,"N") represents the single hexadecimal value $4E, the "N" is mnemonic for DT_NAM, the name record type.
Major types
DM_DEV ($81) RAM device (internal use only)
DM_CHD ($82) Character Device (pseudo type, internal use only)
(SCR.0, PRT.0, COM.0, NUL.0, INP.0, OUT.0)
DM_ROM ($83) ROM Information, consists of three record types:
DT_INF ($40,"@") application information
DT_HLP ($48,"H") help information
DT_NAM ($4E,"N") name of application DM_EPR ($84) EPR device (eprom file area)
NOTE: It is not possible to add external device drivers to the system via a DOR, despite the major types shown above. This is because device drivers are not integrated into the DOR system.
Minor Types
DN_FIL ($11) File type, consists of four record types:
DT_NAM ($4E,"N") file name
DT_CRE ($43,"C") creation time
DT_UPD ($55,"U") update time
DT_EXT ($58,"X") extent (size of file)
DN_DIR ($12) Directory type, consists of three record types:
DT_NAM ($4E,"N") directory name
DT_CRE ($43,"C") creation time
DT_UPD ($55,"U") update time
DN_APL ($13) Application Front DOR Type, consists of record type:
DT_NAM ($4E,"N") Name of front DOR; the name
will be "APPL" for applications
and "HELP" for help.
DN_DEL ($7F) Deleted Entry Type
Record Types
DT_NAM ($4E,"N") Name type. Name must be null-terminated. Filenames have
a fixed length of 17 characters so, if the real
filename is shorter, you will need to ignore excess
characters (beyond the null-terminator). A name record
might look like this:
DEFM $4E & $05 & "Paul" & 0
DT_UPD ($55,"U") Last Updated Date. 6 bytes. 3 bytes internal time
followed by 3 bytes internal date.
DT_CRE ($43,"C") Creation Date. 6 bytes. 3 bytes internal time
followed by 3 bytes internal date.
DT_EXT ($58,"X") Extent of file. 4 byte long word (low byte first)
DT_ATR ($41,"A") Attributes. Not currently used. 2 bytes.
DT_HLP ($48,"H") Help type. 12 bytes: four 3 byte link pointers
(offset+bank): Topics, command, help and tokens. See an
example in "Application Static Strucures" section.
DT_INF ($40,"@") Information. See an example in "Application Static
Structures" section for details of format.
The DOR interface
DORs are manipulated using the OS_Dor call, which is supplied with various reason codes, one for each DOR operation. The possible operations are:
DR_GET ($01) get a handle for a DOR name (system use)
DR_DUP ($02) duplicate DOR
DR_SIB ($03) return brother DOR
DR_SON ($04) return child DOR
DR_FRE ($05) free DOR handle
DR_CRE ($06) create blank DOR
DR_DEL ($07) delete DOR
DR_INS ($08) insert DOR
DR_RD ($09) read DOR record
DR_WR ($0A) write DOR record
DR_RD2 ($0B) read DOR record (system use only)
The following is the interface system call definition:
RST 20H, DEFB $87 In: A = reason code HL, IX arguments Other register usage depends on reason code Out, if call successful: Fc = 0 returned values depend on A(in) Out, if call failed: Fc = 1 A = error code: RC_BAD ($04), bad arguments RC_HAND ($08), bad handle RC_ROOM ($07), no room RC_EOF ($09), end of file
Each reason code operation action is described in detail with the OS_Dor call in the "System Calls Reference" section.
Example
The following example reads the last updated date of a file, which can only be done by reading the DOR of the file. To get a DOR handle for a file, the user must use the GN_Opf call with A = OP_DOR ($06). This differs from the other options of GN_Opf in that:
1) It does not open the file. 2) It returns a DOR handle rather than a file handle
Note that the file should be closed before the call is made, and that it is necessary to free the DOR handle after you have finished, by using OS_Dor with reason code DR_FRE.
include "fileio.def" ; file I/O call definitions & parameters include "dor.def" ; DOR interface call definitions include "time.def" ; Date & time call definitions include "stdio.def" ; standard I/O call defs. & parameters ; assume HL points to local filename and DE points to a dummy buffer ; and 'buff' is at least 6 bytes of temporary workspace ; note, 'buff' must not occur in segment 2, or GN_Sdo will fail .start ld b, 0 ; HL is a local pointer ld c, 20 ; max. size of expanded filename ld a, OP_DOR ; get DOR handle oz GN_Opf ; get DOR information ld a, DR_RD ; read DOR record ld b, DT_UPD ; look at record 'U' (update time) ld c, 6 ; return time information ld de, buff ; return data at (DE) oz OS_Dor ; fetch DOR information ld a, DR_FRE oz OS_Dor ; free DOR handle ld hl, buff ; HL points to internal time, date format oz GN_Sdo ; write time & date to standard output oz GN_Nln ; new line ret