Appendix C - Header Format for Dictionary Names
QED-Forth compiles executable machine code, also called object code, into the definitions area of the dictionary. The current location in the definitions area of the dictionary is given by DP (definitions pointer). QED-Forth compiles the names of the defined routines, also called headers, into the name area of the dictionary. The current location in the name area is given by NP (name pointer). The name area comprises a linked list of headers. Each header contains information about the name (usually a recognizable word that reflects the function of the routine), a pointer to the object code, and a link offset that points to the prior header in the linked list.
Figure C.1 shows the contents of a name area containing two linked headers.
Figure C.1. Diagram of the contents of two headers in the name area.
NP points to the next available byte in the name area of the dictionary. CONTEXT returns an extended address whose contents are the extended address of an xhandle (typically VFORTH) whose contents point to the top nfa in the linked list. Note the two levels of indirection; these are needed to implement different vocabularies. CONTEXT X@ X@ returns the top name field address (xnfa, the address of the count byte) in the search order; CURRENT X@ X@ returns the top xnfa in the list to which the next word will be appended.
The link address offset is a 16-bit signed quantity that gives the offset from the nfa just above the link to the prior nfa in the linked name list. The link page offset is a signed 8 bit quantity that specifies the next page in the linked list. When a link address and page offset of 0 is encountered, it flags the end of a linked list.
The cfa is the code field address; this is the first byte associated with the given word in the object area. Executable machine code must be stored at the cfa. Note that 24 bits are needed to specify the cfa (a 16 bit machine address and an 8 bit page).
Name Field Attributes
The count byte in the header uses 5 bits to hold the number of characters in the name (to a maximum of 31 characters) and the remaining three bits to flag whether the word is immediate, whether it has a pfa, and whether the name is smudged. The following three words control the setting of these bits:
SMUDGE ( -- ) \ toggle bit 5 in the count byte of the latest word defined HAS.PFA ( -- ) \ set bit 6 in the count byte of the latest word defined IMMEDIATE ( -- ) \ set bit 7 in the count byte of the latest word defined
SMUDGE is executed by : and CODE to flag that the word has not been completely defined; it is executed again by ; and END.CODE to clear the smudge bit so the word can be found. HAS.PFA is executed by <VBUILDS and <DBUILDS because all words defined with the <xBUILDS DOES> construction have a parameter field. If the programmer wishes a word to be flagged as IMMEDIATE (i.e., to be executed immediately even if QED-Forth is in compilation mode), IMMEDIATE should be executed just after the word is defined.
The states of the pfa and immediate bits can be checked with the words:
?HAS.PFA ( xnfa -- flag ) \ flag is true if word has a pfa ?IMMEDIATE ( xnfa -- flag ) \ flag is true if word is immediate