Forth v4.4 Function Glossary (!-A-D)

This glossary provides detailed definitions for the general purpose words (Forth functions) available in the v4.4 Forth kernel. Separate glossaries define the assembler and C debugging words available. A separate page lists all the Forth V4.4 Functions that Disable Interrupts.

For help in understanding the notation used in the following function definitions, consult the description of stack symbols, abbreviations and naming conventions.

This glossary is split into three web pages, for words beginning with the following characters (in ASCII alphabetical) order:

! ( w\xaddr -- )

Stores a 16-bit number w at the extended address xaddr. The high order byte is stored at xaddr and the low order byte at xaddr+1. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "store"

" ( -- x$addr )

Compile Time: ( <text> – )

Parses the <text> string in the input stream delimited by a terminating " character. If compiling, emplaces the text in the dictionary as a counted string along with a call to a routine that pushes x$addr to the stack at runtime. If executing, emplaces the string in the dictionary at HERE and leave x$addr (the address of the string) on the stack.
Pronunciation: "quote"
Attributes: I

# ( ud1 -- ud2 )

Divides unsigned double number ud1 by the value in BASE to compute the unsigned double quotient ud2 and the integer remainder n. Converts n to an appropriate single ASCII digit character in the current number base and inserts it into the pictured numeric output string below PAD. # is used between <# and #> commands to create a pictured numeric string.
Pronunciation: "number-sign"
Attributes: S

#> ( d -- xaddr\cnt )

Drops d and leaves the xaddr under the count of the pictured numeric output string resulting from the number conversion process initiated by <#. The character count is also stored in location xaddr - 1, so xaddr - 1 can be used as an x$addr. Used to terminate a pictured numeric output sequence which was opened by <# . The pictured numeric output string is located below PAD.
Pronunciation: "number-sign-greater"

#FIND ( <name> -- [ xcfa\xnfa\flag ] or [ 0 ] )

Executes BL WORD to parse the next space-delimited word from the input stream, and then searches the dictionary for a match of the parsed word. #FIND first searches the CONTEXT vocabulary. Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary. If the word is not found in the dictionary, it leaves a 0 on the stack. If the word is found, it leaves the word's extended code field address under its extended name field address under a flag on the stack. The flag is +1 if the word is immediate and -1 if the word is not immediate. An error occurs if the input stream is exhausted while WORD executes. A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary. This prevents the interpreter from going on an infinite search through a corrupted dictionary. A COLD restart will also occur if POCKET is not in common memory.
Pronunciation: "hash-find"

#INPUT.CHARS ( -- n )

Places on the stack the number of characters in the input queue of the secondary serial port (serial2). In other words, returns the number of characters that have been received by the serial2 input interrupt service routine that have not yet been removed from the circular input buffer by KEY2. The default serial2 input buffer holds 80 characters and is located in the system RAM (consult the memory map appendix in the Software Manual for its location). The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output).
Pronunciation: "number-input-chars"

#OUTPUT.CHARS ( -- n )

Places on the stack the number of characters in the output queue of the secondary serial port (serial2). In other words, returns the number of characters that have been placed in the output buffer by EMIT2 that have not yet been removed from the circular output buffer by the serial2 output interrupt service routine. The default serial2 output buffer holds 80 characters and is located in the system RAM (consult the memory map appendix in the Software Manual for its location). The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output).
Pronunciation: "number-output-chars"

#S ( ud1 -- ud2 | ud2 = 0\0 )

Converts all digits of the unsigned double number ud1 by iteratively dividing quotients by BASE and inserting the ASCII symbol for the remainder into the pictured numeric output starting at the left of the string and working towards the right. ud2 is a double number zero. If ud1 equals zero, a single 0 is added to the pictured output buffer below PAD. #S is used between <# and #> commands to create pictured numeric output.
Pronunciation: "number-sign-s"
Attributes: S

#TIB ( -- xaddr )

User variable that contains the number of characters in the terminal input buffer (TIB).

See also QUERY
Pronunciation: "number-t-i-b"
Attributes: U

#USER.BYTES ( -- n )

n is the number of USER bytes already allocated by QED-Forth. This quantity is useful if the programmer wants to define more user variables. The first additional user variable would be defined as #USER.BYTES USER <name> .

$>DISPLAY ( x$addr\n1\n2 -- | n1 = line#, n2 = character# )

Moves the contents of the counted string specified by x$addr to the location in DISPLAY.BUFFER starting at the specified character number n2 on the specified line number n1. Does not move the count of x$addr. Confines the string to the specified line in DISPLAY.BUFFER by clamping the number of characters moved to a maximum equal to the number of character positions remaining after the specified position on the specified line. The line number n1 should be less than LINES/DISPLAY, and the character number n2 should be less than CHARS/DISPLAY.LINE. If the most significant byte of the page in x$addr equals 0xFF, $>DISPLAY accepts a null-terminated (C-style) string. $>DISPLAY does not modify the contents of the LCD display; this will occur upon the next execution of UPDATE.DISPLAY.LINE or UPDATE.DISPLAY or (UPDATE.DISPLAY).
Pronunciation: "string-to-display"

$>F ( x$addr -- [r\-1] or [0] )

Removes the next space-delimited text string from the input stream and attempts to convert it into a valid floating point number r. Returns r under a true flag if the conversion is successful; otherwise returns a false flag.
Pronunciation: "string-to-f"
Attributes: S

$COMPARE ( xaddr1\xaddr2\+n1 -- +n2 )

Finds the number of common characters +n2 in the strings whose first characters are stored at xaddr1 and xaddr2, respectively. +n1 specifies the maximum number of characters to be compared. Comparison starts at the specified addresses and terminates as soon as an unmatched pair of characters is encountered. +n2 = 0 if there are no common characters found (i.e., if the character at xaddr1 is different from that at xaddr2) or if +n1 is negative. The strings may cross page boundaries.
Pronunciation: "string-compare"

$MOVE ( x$addr\xaddr\n -- )

Moves the contents of the counted string specified by x$addr to the destination starting at xaddr. Does not move the count byte. The number of characters moved is clamped to a maximum of n bytes.
Pronunciation: "string-move"

' ( -- [xpfa] or [0\0] )

Compile Time: ( <name> – )

Removes <name> from the input stream and returns <name>'s extended parameter field address. Returns 0\0 if <name> has no parameter field (see ?HAS.PFA). If in execution mode, leaves the xpfa on the stack. If in compilation mode, compiles the xpfa as a 2-cell literal in the current definition; the xpfa is pushed to the stack when the definition later executes. An error occurs if no <name> is given or if <name> cannot be found in the dictionary.
Pronunciation: "tick"
Attributes: I

( ( -- )

Compile Time: ( <text)> – )

Ignores all further input until ) or the end of the input stream is encountered. Used to enclose comments. No error occurs if the end of the input stream is encountered. When used in a block, the terminating ) can be on a different line than (. However, when used from the terminal, only single line comments are allowed

See also \
Pronunciation: "paren"
Attributes: I

(!) ( w\addr -- )

Stores a 16-bit number at addr on the current page or in common memory. The high order byte is stored at addr and the low order byte at addr+1.
Pronunciation: "paren-store"

(#FIND) ( $addr -- [ xcfa\xnfa\flag ] or [ 0 ] )

Searches the dictionary for a match of the counted string at $addr in the common memory. (#FIND) first searches the CONTEXT vocabulary. Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary. If the word is not found in the dictionary, (#FIND) leaves a 0 on the stack. If the word is found, it leaves the word's extended code field address under its extended name field address under a flag on the stack. The flag is +1 if the word is immediate and -1 if the word is not immediate. A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary. This prevents the interpreter from going on an infinite search through a corrupted dictionary. A COLD restart will also occur if POCKET is not in common memory.
Pronunciation: "paren-hash-find"

((ERROR)) ( [...]\error.id -- )

The default routine called by (ERROR) if a system error is detected and the CUSTOM.ERROR flag is false. Prints a descriptive error message, if possible printing the name of the routine that detected the error and any arrays or matrices involved in producing the error condition. Unlike (ERROR), ((ERROR)) does not execute ABORT. In multitasking applications, the availability of ((ERROR)) allows a task with access to the serial line to print intelligible system error messages without executing ABORT. Since ABORT invokes the user-installed autostart routine in a turnkeyed system, the ability to handle errors without invoking ABORT increases the programmer's options. For example, the following user-defined error handler can be installed in UERROR to allow a task to print standard error messages without calling ABORT or invoking an installed autostart routine:

: MY.ERROR.HANDLER   ( -- )
   ((ERROR))      \ prints proper error messages
   SP!  RP!      \ initialize data & return stacks
   FORTH DEFINITIONS   \ initialize vocabulary
   QUIT   ;         \ enter interpreter
CFA.FOR MY.ERROR.HANDLER UERROR X!
CUSTOM.ERROR ON      \ install task's error handler

See also (ERROR), CUSTOM.ERROR, UERROR, and ABORT
Pronunciation: "paren-paren-error"

(+!) ( w\addr -- )

Adds w to the 16-bit value stored at addr on the current page or in common memory and stores the result at addr.
Pronunciation: "paren-plus-store"

(+C!) ( byte\addr -- )

Adds byte to the 8-bit value at addr on the current page or in common memory and stores the result at addr.
Pronunciation: "paren-plus-c-store"

(2!) ( w1\w2\addr -- | [addr] gets w2, [addr+2] gets w1 )

Stores two 16-bit integers at addr on the current page or in common memory. w2 is stored at addr and w1 is stored at addr+2. Can also be used to store a double number at addr.
Pronunciation: "paren-two-store"

(2@) ( addr -- w1\w2 )

Fetches two 16-bit integers from addr and addr+2 on the current page or in common memory. w2 is taken from addr and the w1 is from addr+2. Can also be used to fetch a double number from addr.
Pronunciation: "paren-two-fetch"

(@) ( addr -- w )

Fetches a 16-bit number from addr on the current page or in common memory. The high order byte is taken from addr and the low order byte from addr+1.
Pronunciation: "paren-fetch"

(A/D8.MULTIPLE) ( xaddr\u1\u2\n -- | u1=timing param; u2 = #samples, n = channel# )

Acquires u2 samples from the 8 bit analog to digital (A/D) converter in the 68HC11 and stores the samples as sequential unsigned 8 bit values starting at the specified xaddr. n specifies the channel number of the A/D (0 < = n < = 7). To maximize speed, this routine does not GET or RELEASE the A/D8.RESOURCE. Consequently, this routine should not be used in a multitasking environment where another task might require access to the 8 bit A/D (see A/D8.MULTIPLE). If the specified xaddr is in common memory, the first sample is taken after 16 microseconds and subsequent samples are taken every (10+2.5*u1) microseconds, where u1 is the specified timing parameter passed to this routine. If the specified xaddr is in paged memory, the first sample is taken after 11 microseconds and subsequent samples are taken every (32.5+2.5*u1) microseconds. Of course, the operation of interrupts (including timesliced multitasking) will affect these sampling times.

See also (A/D8.SAMPLE), A/D8.SAMPLE, A/D8.MULTIPLE, and A/D8.ON
Pronunciation: "paren-A-to-D-eight-multiple"

(A/D8.SAMPLE) ( n -- byte | n = channel# )

Acquires and places on the stack a single sample byte from the 8 bit analog to digital converter in the 68HC11. n specifies the A/D channel number (0 < = n < = 7). To maximize speed, this routine does not GET or RELEASE the A/D8.RESOURCE. Consequently, this routine should not be used in a multitasking environment where another task might require access to the 8 bit A/D; (see A/D8.SAMPLE). This routine executes in 23 microseconds.

See also A/D8.SAMPLE, (A/D8.MULTIPLE), A/D8.MULTIPLE, and A/D8.ON
Pronunciation: "paren-A-to-D-eight-sample"

(ABORT) ( [...] -- )

Return Stack: ( R: […] – )

The default abort routine called by ABORT if the CUSTOM.ABORT flag is false. Clears the data and return stacks, sets the page to the default page (0), and executes FORTH DEFINITIONS to set CONTEXT and CURRENT equal to FORTH. If an autostart vector has been installed (see AUTOSTART), (ABORT) executes the specified routine; otherwise it executes QUIT which sets the compilation mode and enters the interpreter. If R0 and S0 aren't in common RAM, a COLD restart is initiated.
Pronunciation: "paren-abort"

(BENCHMARK:) ( <name> -- u1\ud\u2\u3 | u1=#msec, ud=#sec, u2=#F*, u3=#F+ )

Removes the next <name> from the input stream and measures and places on the stack the execution time and operations count of <name>. Use as:

(BENCHMARK:) <name>

The multitasker's timeslicer clock must be running for the execution time to be measured; use START.TIMESLICER to start it before calling (BENCHMARK:). Any stack arguments needed by <name> should be placed on the stack before (BENCHMARK:) is invoked. If <name> leaves any items on the stack, they will be below the stack items left by (BENCHMARK:). Net execution time of <name> is represented by ud seconds + u1 msec. The resolution of the measurement equals the timeslice period which can be set using the command *100US=TIMESLICE.PERIOD; the default is 5 msec. u2 is the number of F* and F/ operations performed by <name> and u3 is the number of F+ and F- operations performed by <name>. Operations counts up to 65,535 can be reported; after that the 16-bit operations counter rolls over to 0 and continues counting. This word is a subsidiary to BENCHMARK: which prints the results instead of leaving them on the stack.
Pronunciation: "paren-benchmark"
Attributes: S

(C!) ( byte\addr -- )

Stores the byte at addr on the current page or in common memory.
Pronunciation: "paren-c-store"

(C@) ( addr -- byte )

Fetches the byte stored at addr on the current page or in common memory.
Pronunciation: "paren-c-fetch"

(CHANGE.BITS) ( byte1\byte2\addr -- | byte1 = data; byte2 = mask )

At the byte specified by addr on the current page or in common memory, modifies the bits specified by 1's in byte2 to have the values indicated by the corresponding bits in byte1. In other words, byte2 serves as a mask that specifies the bits at addr that are to be modified, and byte1 provides the data that is written to the modified bits. Disables interrupts for 16 cycles (4 microseconds) to ensure an uninterrupted read/modify/write operation. Executes more rapidly than CHANGE.BITS.
Pronunciation: "paren-change-bits"

(CLEAR.BITS) ( byte1\addr -- )

For each bit of byte1 that is set, clears the corresponding bit of the 8 bit value at addr on the current page or in common memory. Disables interrupts for ten cycles (2.5 microseconds) to ensure an uninterrupted read/modify/write operation. Executes more rapidly than CLEAR.BITS.
Pronunciation: "paren-clear-bits"

(CMOVE) ( addr1\addr2\u -- | addr1=src, addr2=dest, u = byte count )

If u is greater than 0, u consecutive bytes starting at addr1 are copied to the destination addresses starting at addr2 on the current page or in common memory. Does not change the page. Speed is approximately 7.5 microseconds per byte. If the source and destination regions overlap and addr1 < addr2, (CMOVE) starts at high memory and moves toward low memory to avoid propagation of the moved contents. (CMOVE) always moves the contents in such a way as to avoid memory propagation.
Pronunciation: "paren-c-move"

(COMPILE.CALL) ( cfa -- )

Compiles a call to the specified cfa. Compiles a JSR (jump to subroutine) opcode followed by cfa into the definitions area at HERE and increments DP by 3. No page change is compiled.
Pronunciation: "paren-compile-call"

(CREATE) ( $addr -- )

Similar to CREATE which creates a header for <name>. The difference is that CREATE removes <name> from the input stream by executing BL WORD, while (CREATE) accepts <name> as a counted string at $addr in common memory. Converts the counted string at $addr to upper case letters and searches the dictionary via (FIND) to check for uniqueness. Issues a warning if <name> is not unique. Creates a new header for <name> starting at the address pointed to by NP, links the header to the CURRENT vocabulary, and initializes the code field address in the header to the current value of DP. Updates the CURRENT vocabulary xhandle to point to the xnfa of <name> and updates NP to point to the byte after <name>'s header. The number of characters saved in the header is the lesser of the value in WIDTH or the actual number of characters in <name>. If locals are compiling, all characters are saved in the header to avoid non-uniqueness of local variables. An abort error occurs if the header cannot be stored (e.g. if NP does not point to RAM). If WIDTH is less than or equal to 1, (CREATE) resets WIDTH to 2.

See also CREATE
Pronunciation: "paren-create"
Attributes: D

(EE!) ( w\addr -- | addr is an EEPROM address )

Stores w at the specified addr in EEPROM. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. Requires 20 msec per programmed byte. Disables interrupts during the programming of each byte. Caution: the prolonged disabling of interrupts by (EE!) can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.
Pronunciation: "paren-e-e-store"

(EE2!) ( w1\w2\addr -- | [addr] gets w2, [addr+2] gets w1 )

Stores w1 and w2 at the specified addr in EEPROM. w2 is stored at addr and w1 is stored at addr+2. Can also be used to store a double number at addr. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. Requires 20 msec per programmed byte. Disables interrupts during the programming of each byte. Caution: the prolonged disabling of interrupts by (EE2!) can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.
Pronunciation: "paren-e-e-two-store"

(EEC!) ( byte\addr -- | addr is an EEPROM address )

Stores byte at the specified addr in EEPROM. If addr already contains the specified contents it is not re-programmed; this helps lengthen the lifetime of the EEPROM. Requires 20 msec per programmed byte. Disables interrupts during the programming of each byte. Caution: the prolonged disabling of interrupts by (EEC!) can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.
Pronunciation: "paren-e-e-c-store"

(EEF!) ( r\addr -- | addr is an EEPROM address )

Stores r at the specified addr in EEPROM. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. Requires 20 msec per programmed byte. Disables interrupts during the programming of each byte. Caution: the prolonged disabling of interrupts by (EEF!) can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.
Pronunciation: "paren-e-e-f-store"

(EEX!) ( xaddr\addr -- | addr is an EEPROM address )

Stores xaddr at the specified addr in EEPROM. Any byte that already contains the specified contents is not re-programmed; this helps lengthen the lifetime of the EEPROM. Requires 20 msec per programmed byte. Disables interrupts during the programming of each byte. Caution: the prolonged disabling of interrupts by (EEX!) can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.
Pronunciation: "paren-e-e-x-store"

(ERROR) ( [...] -- )

Return Stack: ( R: […] – )

The default routine called if a system error is detected and the CUSTOM.ERROR flag is false. Prints a descriptive error message, if possible printing the name of the routine that detected the error and any arrays or matrices involved in producing the error condition. After printing the message, executes ABORT.

See also ((ERROR)), CUSTOM.ERROR, UERROR, and ABORT
Pronunciation: "paren-error"

(EXECUTE) ( cfa -- )

Executes (calls) the routine whose executable machine instructions begin at the specified code field address cfa on the current page or in common memory.
Pronunciation: "paren-execute"

(F!) ( r\addr -- )

Stores a floating point number at addr on the current page or in common memory.
Pronunciation: "paren-f-store"

(F@) ( addr -- r )

Fetches a floating point number from addr on the current page or in common memory.
Pronunciation: "paren-f-fetch"

(FIND) ( $addr -- [ xcfa\flag ] or [ 0 ] )

Searches the dictionary for a match of the counted string at $addr in the common memory. (FIND) first searches the CONTEXT vocabulary. Then, if the word is not found and if the CONTEXT and CURRENT vocabularies are different, it searches the CURRENT vocabulary. If the word is not found in the dictionary, (FIND) leaves a 0 on the stack. If the word is found, it leaves the word's extended code field address under a flag on the stack. The flag is +1 if the word is immediate and -1 if the word is not immediate. A COLD restart will occur if more than 255 page changes are made during the search through either vocabulary. This prevents the interpreter from going on an infinite search through a corrupted dictionary. A COLD restart will also occur if POCKET is not in common memory.
Pronunciation: "paren-find"
Attributes: D

(HERE) ( -- addr )

Places on the stack the addr of the next available location in the definitions area. Equivalent to DP 2XN+ @
Pronunciation: "paren-here"
Attributes: U

(MOVE) ( addr1\addr2\u -- | addr1=src, addr2=dest, u = count )

If u is greater than 0, u consecutive 16-bit numbers (i.e., 2*u consecutive bytes) starting at addr1 are copied to the destination addresses starting at addr2 on the current page or in common memory. Does not change the page. Speed is approximately 15 microseconds per 2-byte cell. If the source and destination regions overlap and addr1 < addr2, (MOVE) starts at high memory and moves toward low memory to avoid propagation of the moved contents. (MOVE) always moves the contents in such a way as to avoid memory propagation.
Pronunciation: "paren-move"

(PAGE.LATCH) ( -- addr )

Returns the address of the page latch whose contents indicate the current page. Be careful when explicitly changing the contents of the page latch. Note that the word C! cannot be used to alter the contents of the page latch because C! saves and restores the page. Rather, the page-less store operator (C!) must be used.

See also THIS.PAGE

(RP) ( -- addr )

Places on the stack the address of the most significant byte of the top item on the return stack.
Pronunciation: "paren-r-p"
Attributes: U

(SET.BITS) ( byte1\addr -- )

For each bit of byte1 that is set, sets the corresponding bit of the 8 bit value at addr on the current page or in common memory. Disables interrupts for ten cycles (2.5 microseconds) to ensure an uninterrupted read/modify/write operation. Executes more rapidly than SET.BITS.
Pronunciation: "paren-set-bits"

(SP) ( -- addr )

Places on the stack the address of the most significant byte of the top cell of the data stack just before (SP) is executed.
Pronunciation: "paren-s-p"
Attributes: U

(STATUS) ( -- addr | addr is also the base addr of the user area )

Returns the address but not the page of the STATUS user variable which is also the task identification address at the base of the task's user area. Because STATUS must be in common memory, a 16-bit address is sufficient to specify its location. Using (STATUS) instead of STATUS leads to faster code because page-less memory operators execute more rapidly than operators that take full extended addresses.

See also STATUS
Pronunciation: "paren-status"
Attributes: U

(TOGGLE.BITS) ( byte1\addr -- )

For each bit of byte1 that is set, reverses the state of the corresponding bit of the 8 bit value at addr on the current page or in common memory. Disables interrupts for ten cycles (2.5 microseconds) to ensure an uninterrupted read/modify/write operation. Executes more rapidly than TOGGLE.BITS.
Pronunciation: "paren-toggle-bits"

(UPDATE.DISPLAY) ( -- )

Writes the contents of the DISPLAY.BUFFER to the LCD display, but does not re-home the cursor/display RAM pointer to the default upper left position. This facilitates "scrolling" the contents of a graphics display when used in conjunction with the IS.DISPLAY.ADDRESS routine. For character displays, the cursor is turned off during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. Intermittently disables interrupts for 28 cycles (7 microseconds) per byte to implement clock stretching.

See also UPDATE.DISPLAY and UPDATE.DISPLAY.LINE

(X!) ( xaddr\addr -- )

Stores an extended address xaddr at addr on the current page or in common memory.
Pronunciation: "paren-x-store"

(X@) ( addr -- xaddr )

Fetches an extended address from addr on the current page or from common memory.
Pronunciation: "paren-x-fetch"

* ( n1\n2 -- n3 )

Multiplies n1 by n2 giving n3 which is the least significant cell of the product.
Pronunciation: "star"

*/ ( n1\n2\n3 -- n4 | do n1*n2/n3 ; n4 = quotient )

Multiplies n1 and n2 producing an intermediate double number result which is divided by n3 to yield the integer quotient n4. Uses signed math. An unchecked error occurs on overflow. Division by zero (n2=0) yields n4 = -1.
Pronunciation: "star-slash"

*/MOD ( n1\n2\n3 -- n4\n5 | do n1*n2/n3; n4 = remainder; n5 = quotient )

Multiplies n1 and n2 producing an intermediate double number result which is divided by n3 to yield remainder n4 and quotient n5. Uses signed math. An unchecked error occurs on overflow. Division by zero (n2=0) yields n4 = -1 and n5 = -1.

See also U*/MOD
Pronunciation: "star-slash-mod"

*100US=TIMESLICE.PERIOD ( u -- )

Sets u as the period of the timeslice clock (the OC2 interrupt) in units of 100 microseconds. For example, to set the timeslice period to 0.8 msec, execute

8  *100US=TIMESLICE.PERIOD

Note that the default timeslice increment set after a COLD restart is 5 msec. Implementation detail: Based on the prescaler bits PR1 and PR0 in the TMSK2 register, this routine calculates the period of the clock driving the OC2 timer. It then calculates the number of these periods in the requested timeslice period u, and stores the resulting OC2 timer increment in a headerless system variable called TIMESLICE.INCREMENT. This stored increment sets the period of the OC2 timer. The period of the OC2 timer determines the timeslice period and also the resolution of the elapsed time clock (see READ.ELAPSED.TIME). Aborts if the calculated increment is 0 or is greater than 65,535.
Pronunciation: "times-100-microseconds-equals-timeslice-period"

+ ( n1\n2 -- n3 )

Adds n1 to n2 and puts the sum n3 on the data stack.
Pronunciation: "plus"

+! ( w\xaddr -- )

Adds w to the 16-bit value stored at xaddr and stores the result at xaddr.
Pronunciation: "plus-store"

+C! ( byte\xaddr -- )

Adds byte to the 8-bit value stored at xaddr and stores the result at xaddr.
Pronunciation: "plus-c-store"

+CURRENT.HEAP ( xpfa -- xpfa+u )

Adds the offset u to the extended parameter field address xpfa. +CURRENT.HEAP is defined as a member of the structure HEAP.STRUCTURE.PF. Use as:

' <name.of.heap.item> +CURRENT.HEAP

to find the address in the heap item's parameter field where the 16-bit current.heap address is stored. CURRENT.HEAP specifies the heap in which the item is allocated.

See also HEAP.STRUCTURE.PF, CURRENT.HEAP, +HEAP.PAGE
Pronunciation: "plus-current-heap"

+HEAP.HANDLE ( xpfa -- xpfa+u )

Adds the offset u to the extended parameter field address xpfa. +HEAP.HANDLE is defined as a member of the structure HEAP.STRUCTURE.PF. Use as:

' <name.of.heap.item> +HEAP.HANDLE

to find the address in the parameter field that contains of the handle which contains the base xaddr of the heap item.

See also HEAP.STRUCTURE.PF and +HEAP.PAGE
Pronunciation: "plus-heap-handle"

+HEAP.PAGE ( xpfa -- xpfa+u )

Adds the offset u to the extended parameter field address xpfa. +HEAP.PAGE is defined as a member of the structure HEAP.STRUCTURE.PF. Use as:

' <name.of.heap.item> +HEAP.PAGE

to find the address of the page of the heap as saved in the item's parameter field. This is the page of the handle as well as the page of CURRENT.HEAP in which the item resides.

See also HEAP.STRUCTURE.PF
Pronunciation: "plus-heap-page"

+LOOP ( n -- )

Return Stack: ( R: w1\w2 – [w1\w2] or [] | drops w1,w2 when loop terminates)

+LOOP adds the signed integer n to the loop index. If the index crossed the boundary between limit-1 and limit (in either direction), the loop parameters are removed from the return stack and execution continues at the word following +LOOP. Otherwise, execution continues at the word following DO. See DO for examples.

Use as:

w1 w2 DO      words to be executed         n +LOOP

where w1 is the loop limit and w2 is the starting index. An error is issued if +LOOP is not properly paired with DO inside a colon definition.

See also DO  LOOP  I  J  I'  K  LEAVE
Pronunciation: "plus-loop"
Attributes: C, I

, ( w -- )

Stores w at the next available location in the definitions area and increments the definitions pointer DP by 2. An error occurs if w is not correctly stored (for example, if DP does not point to RAM). An error occurs if the operation causes DP to be incremented across the boundary between 0x7FFF (the last valid address in a given page) and 0x8000 (the start of the register area).
Pronunciation: "comma"

," ( -- )

Compile Time: ( <text> – )

Parses the <text> string delimited by a " character from the input stream and emplaces the string in the dictionary starting at HERE. An error occurs if the compiled string crosses a page boundary.
Pronunciation: "comma-quote"

- ( n1\n2 -- n3 | n3 = n1 - n2 )

Subtracts n2 from n1 and puts the result n3 on the data stack.
Pronunciation: "minus"

-1 ( -- -1 )

Puts the value negative one on the data stack.
Pronunciation: "minus-one"

-1/INFINITY ( -- r )

Pushes the smallest representable negative floating point number onto the data stack.
Pronunciation: "minus-one-over-infinity"

-2 ( -- -2 )

Puts the value negative two on the data stack.
Pronunciation: "minus-two"

-INFINITY ( -- r )

Pushes the negative of the largest representable floating point number onto the data stack.
Pronunciation: "minus-infinity"

-ROLL ( wn\...\w0\+n -- w0\wn\...\w1 | 0 <= +n <= 255 )

Transfers the top item (not including +n) on the data stack to the nth position from the top of the data stack, where the top stack item is item#0, the next is item#1, etc. For example, 0 ROLL does nothing, 1 -ROLL is equivalent to SWAP, and 2 -ROLL is equivalent to -ROT.
Pronunciation: "minus-roll"

-ROT ( w1\w2\w3 -- w3\w1\w2 )

Rotates the top three stack entries by moving the top cell below the next two cells on the data stack.
Pronunciation: "minus-rot"

-TRAILING ( xaddr\u1 -- xaddr\u2 )

Strips trailing space characters from the string located at xaddr by returning the new character count, u2, of the text string with spaces removed. Equivalent to BL SKIP>
Pronunciation: "dash-trailing"

. ( n -- )

Prints n with no leading spaces and 1 trailing space. If the number base is decimal, w is printed as a signed number in the range -32,768 to +32,767. In other bases w is printed as an unsigned positive number. Use U. to print w as a positive unsigned number in decimal base.
Pronunciation: "dot"
Attributes: M, S

." ( -- )

Compile Time: ( <text> – )

Parses the <text> string in the input stream delimited by a terminating " character. If executing, types the <text>. If compiling, emplaces the text in the dictionary as a counted string along with a call to a routine that types the <text> at runtime. An error occurs if the compiled string crosses a page boundary.
Pronunciation: "dot-quote"
Attributes: I, M

.HANDLES ( -- )

Prints the allocated handles of the current heap in tabular format, listing the size, base xaddress, and handle xaddress of each heap item. All quantities are displayed in hexadecimal base. An * displayed in the size field indicates that the handle is not in use (i.e., it has been returned to the heap) or its contents are invalid.
Pronunciation: "dot-handles"
Attributes: M

.R ( w\+byte -- | +byte is field width )

Prints w right-justified in a field of +byte characters. If +byte is less than or equal to the number of characters to be printed, the number is printed with no extra spaces. If the number base is decimal, w is printed as a signed number in the range -32,768 to +32,767. In other bases w is printed as an unsigned positive number. To print w as a positive unsigned number in decimal base, place a 0 on the stack above w to convert it into a positive double number and call UD.R
Pronunciation: "dot-r"
Attributes: M, S

.S ( -- )

Displays the contents of the data stack without modifying the contents of the stack. Prints the number of 1-cell stack items in brackets and displays the stack items separated by \ (read as "under"). A maximum of 5 items are displayed. For example, if there are 7 stack items having values 1…7 with 1 on top of the stack and 7 farthest down, executing .S yields

( 7 ) \ 5 \ 4 \ 3 \ 2 \ 1   ok

In execution mode, the stack contents are automatically displayed after each line is interpreted if the DEBUG flag is true. The stack is also displayed during a TRACE of a compiled routine.
Pronunciation: "dot-s"
Attributes: M, S

/ ( n1\n2 -- n3 | n3 = n1/n2 )

Divide n1 by n2, giving the quotient n3. If the division does not produce an integer quotient, the quotient is rounded towards 0. Division by 0 (n2=0) produces a quotient of -1.

See also U/
Pronunciation: "slash"

/MOD ( n1\n2 -- n3\n4 | n3 = remainder, n4 = quotient )

Divide n1 by n2, giving the remainder n3 and the quotient n4. The quotient is rounded towards 0, and the remainder carries the sign of n1. Division by 0 (n2=0) yields n3 = n4 = -1.

See also U/MOD
Pronunciation: "slash-mod"

/STRING ( xaddr1\u1\n -- xaddr2\u2 )

Shortens the text string whose first character is at xaddr1 by computing xaddr2 = xaddr1 + n and u2 = u1 - n. u1 and u2 are 16 bit text string counts. n may be negative, and the string may cross a page boundary.
Pronunciation: "slash-string"

0 ( -- 0 )

Puts the value zero on the data stack.
Pronunciation: "zero"

0< ( n -- flag )

Flag is TRUE if n is less than zero and FALSE otherwise.
Pronunciation: "zero-less-than"

0<> ( w -- flag )

Flag is TRUE if w is not equal to zero and FALSE otherwise.
Pronunciation: "zero-not-equal"

0= ( w -- flag )

Flag is TRUE if w is equal to zero and FALSE otherwise.
Pronunciation: "zero-equals"

0> ( n -- flag )

Flag is true if n is greater than zero and FALSE otherwise.
Pronunciation: "zero-greater-than"

0\0 ( -- 0\0 )

Places two zeros on the top of the stack.
Pronunciation: "0-under-0"

1 ( -- 1 )

Puts the value one on the data stack.
Pronunciation: "one"

1+ ( w1 -- w2 | w2 = w1 + 1 )

Adds 1 to w1 giving the sum w2.
Pronunciation: "one-plus"

1- ( w1 -- w2 | w2 = w1 - 1 )

Subtracts 1 from w1 giving w2.
Pronunciation: "one-minus"

1/F ( r1 -- r2 )

r2 is the multiplicative inverse of r1; r2 = 1.0/r1.
Pronunciation: "one-over-f"
Attributes: S

1/INFINITY ( -- r )

Places the smallest representable positive floating point number on the data stack.
Pronunciation: "one-over-infinity"

1/LN(2) ( -- r )

Places the floating point representation of the inverse of the natural logarithm of 2 (1.4427) on the stack.
Pronunciation: "one-over-l-n-of-two"

1/LOG10(2) ( -- r )

Places the floating point representation of the inverse of the base 10 logarithm of 2 (3.3219) on the stack.
Pronunciation: "one-over-log-ten-of-two"

1/PI ( -- r )

Places the floating point representation of 1/pi (0.3183) on the stack.
Pronunciation: "one-over-pi"

1/SQRT(2) ( -- r )

Places the floating point representation of the inverse of the square root of 2 (0.7071) on the stack.
Pronunciation: "one-over-square-root-of-two"

1/TEN ( -- r )

Places r = 0.1 on the data stack.
Pronunciation: "one-over-ten"

10* ( n1 -- n2 | n2 = n1 * 10 )

Multiplies n1 by 10 (decimal) giving n2.
Pronunciation: "ten-star"

10^N ( n -- r )

r equals 10 to the nth power; r = 10^n.
Pronunciation: "ten-to-the-n"
Attributes: S

1XN+ ( xaddr1 -- xaddr2 )

Adds 1 to xaddr1 yielding xaddr2. Equivalent to 1 XN+ .
Pronunciation: "one-x-n-plus"

1XN- ( xaddr1 -- xaddr2 )

Subtracts 1 from xaddr1 yielding xaddr2. Equivalent to 1 XN- .
Pronunciation: "one-x-n-minus"

2 ( -- 2 )

Puts the value two on the data stack.
Pronunciation: "two"

2! ( w1\w2\xaddr -- | [xaddr] gets w2, [xaddr+2] gets w1 )

Stores two 16-bit integers at xaddr. w2 is stored at xaddr and w1 is stored at xaddr+2. Can also be used to store a double number at xaddr. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "two-store"

2* ( n1 -- n2 | n2 = n1 * 2 )

Multiplies n1 by 2 giving n2.
Pronunciation: "two-star"

2+ ( w1 -- w2 | w2 = w1 + 2 )

Adds 2 to w1 giving the sum w2.
Pronunciation: "two-plus"

2- ( w1 -- w2 | w2 = w1 - 2 )

Subtracts 2 from w1 giving w2.
Pronunciation: "two-minus"

2/ ( n1 -- n2 | n2 = n1 / 2 )

Divides n1 by 2 giving n2.

See also U2/
Pronunciation: "two-slash"

2@ ( xaddr -- w1\w2 )

Fetches two 16-bit integers from xaddr. w2 is taken from xaddr and w1 is from xaddr+2. Can also be used to fetch a double number from xaddr. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "two-fetch"

2ARRAY.FETCH ( row#\col#\xpfa -- d )

Fetches and places on the data stack the contents of the element at row#, column# in the specified 2-dimensional array or matrix. The size of the element that is fetched depends upon the number of bytes per element of the array or matrix as specified by DIMENSIONED or DIMMED, and the result is always padded out to 4 bytes on the stack. There is an unchecked error if the specified array or matrix does not have 2 dimensions or if the number of bytes per element does not equal 1, 2, or 4.

See also M[]@
Pronunciation: "two-array-fetch"

2ARRAY.STORE ( d\ row#\col#\xpfa -- )

Stores the specified byte-, 2 byte-, or 4 byte-data at the element specified by row#, column# in the specified 2-dimensional array or matrix. The size of the element that is stored can be 1 byte, 2 bytes, or 4 bytes depending upon the number of bytes per element of the array or matrix as set by DIMENSIONED or DIMMED. There is an unchecked error if the specified array or matrix does not have 2 dimensions or if the number of bytes per element does not equal 1, 2, or 4.

See also M[]!
Pronunciation: "two-array-store"

2CONSTANT ( wd <name> -- )

Removes the next <name> from the input stream and defines a child word called <name> which when executed leaves the 32-bit value wd on the data stack. wd is stored in the definitions area of the dictionary. <name> is referred to as a "2constant". Use as:

wd  2CONSTANT  <name>

Pronunciation: "two-constant"
Attributes: D

2DROP ( w1\w2 -- )

Drops the top two cells from the data stack.
Pronunciation: "two-drop"

2DUP ( w1\w2 -- w1\w2\w1\w2 )

Duplicates the top two cells on the data stack.
Pronunciation: "two-dupe"

2DUP>R ( w1\w2 -- w1\w2 )

Return Stack: ( R: – w1\w2 )

Copies the top cell pair on the data stack to the return stack.
Pronunciation: "2-dup-to-r"
Attributes: C

2LITERAL ( -- wd )

Compile Time: ( wd – )

If QED-Forth is in execution mode when 2LITERAL is invoked, 2LITERAL does nothing. If QED-Forth is in compilation mode, 2LITERAL removes wd from the stack and compiles it into the dictionary along with code that, when later executed, pushes wd to the stack. 2LITERAL can be used within a colon definition to compile a numeric value into the definition. For example,

: <name>
   ... [ 1234 1000 * ] 2LITERAL ...
;

This compiles the value calculated between [ and ] as a double literal into the definition of <name>. When <name> is executed, this value will be placed on the stack.
Pronunciation: "two-literal"
Attributes: C, I

2OVER ( w1\w2\w3\w4 -- w1\w2\w3\w4\w1\w2 )

Places a copy of cell pair w1\w2 on the top of the stack.
Pronunciation: "two-over"

2PI/360 ( -- r )

Places the floating point representation of 2pi/360 (0.017453) on the stack.
Pronunciation: "two-pi-over-three-sixty"

2ROT ( w1\w2\w3\w4\w5\w6 -- w3\w4\w5\w6\w1\w2 )

Rotates the top three cell pairs on the data stack.
Pronunciation: "two-rote"

2SWAP ( w1\w2\w3\w4 -- w3\w4\w1\w2 )

Exchanges the top two cell pairs on the data stack.
Pronunciation: "two-swap"

2V.TRANSFORM ( xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el\xcfa -- )

xcfa specifies a floating point transformation that operates on two input numbers to produce a single floating point result. 2V.TRANSFORM applies this transformation to each pair of corresponding elements in two source vectors specified by xvaddr1\sep1\d.#el and xvaddr2\sep2\d.#el and places the result in the destination vector specified by xvaddr3\sep3\d.#el. The destination vector may be either of the sources.
Pronunciation: "two-v-transform"
Attributes: S

2VARIABLE ( <name> -- )

Removes the next <name> from the input stream, defines a child word called <name>, and VALLOTs 2 cells in the variable area. When <name> is executed it leaves the extended address xaddr of the two cells reserved in the variable area that hold <name>'s contents. <name> is referred to as a "2variable". Use as:

  2VARIABLE <name>

Pronunciation: "2-variable"
Attributes: D

2XN+ ( xaddr1 -- xaddr2 )

Adds 2 to xaddr1 yielding xaddr2. Equivalent to 2 XN+ .
Pronunciation: "two-x-n-plus"

2XN- ( xaddr1 -- xaddr2 )

Subtracts 2 from xaddr1 yielding xaddr2. Equivalent to 2 XN- .
Pronunciation: "two-x-n-minus"

3 ( -- 3 )

Puts the value three on the data stack.
Pronunciation: "three"

3* ( n1 -- n2 | n2 = n1 * 3 )

Multiplies n1 by 3 giving n2.
Pronunciation: "three-star"

360/2PI ( -- r )

Places the floating point representation of 360/2pi (57.296) on the stack.
Pronunciation: "three-sixty-over-two-pi"

3DROP ( w1\w2\w3 -- )

Drops the top three cells from the data stack.
Pronunciation: "three-drop"

3DUP ( w1\w2\w3 -- w1\w2\w3\w1\w2\w3 )

Duplicates the top three cells on the data stack.
Pronunciation: "three-dupe"

4 ( -- 4 )

Puts the value four on the data stack.
Pronunciation: "four"

4* ( n1 -- n2 | n2 = n1 * 4 )

Multiplies n1 by 4 giving n2.
Pronunciation: "four-star"

4+ ( w1 -- w2 | w2 = w1 + 4 )

Adds 4 to w1 giving the sum w2.
Pronunciation: "four-plus"

4- ( w1 -- w2 | w2 = w1 - 4 )

Subtracts 4 from w1 giving w2.
Pronunciation: "four-minus"

4/ ( n1 -- n2 | n2 = n1 / 4 )

Divides n1 by 4 giving n2.
Pronunciation: "four-slash"

4DROP ( w1\w2\w3\w4 -- )

Drops the top 4 cells from the data stack.
Pronunciation: "four-drop"

4DUP ( w1\w2\w3\w4 -- w1\w2\w3\w4\w1\w2\w3\w4 )

Duplicates the top four cells on the data stack.
Pronunciation: "four-dupe"

4XN+ ( xaddr1 -- xaddr2 )

Adds 4 to xaddr1 yielding xaddr2. Equivalent to 4 XN+ .
Pronunciation: "four-x-n-plus"

4XN- ( xaddr1 -- xaddr2 )

Subtracts 4 from xaddr1 yielding xaddr2. Equivalent to 4 XN- .
Pronunciation: "four-x-n-minus"

8* ( n1 -- n2 | n2 = n1 * 8 )

Multiplies n1 by 8 giving n2.
Pronunciation: "eight-star"

8/ ( n1 -- n2 | n2 = n1 / 8 )

Divides n1 by 8 giving n2.
Pronunciation: "eight-slash"

8XN+ ( xaddr1 -- xaddr2 )

Adds 8 to xaddr1 yielding xaddr2. Equivalent to 8 XN+ .
Pronunciation: "eight-x-n-plus

: ( < name> -- )

Starts the compilation of a new definition. Removes <name> from the input stream and creates a header for <name> in the dictionary. The header is SMUDGEd so that it cannot be found until ; executes to successfully terminate the definition. Enters the compile mode so that words following : are compiled into the code field of <name> (but IMMEDIATE words are executed immediately instead of being compiled). A "<name> isn't unique" warning is issued if <name> already exists in the dictionary. The contents of CONTEXT and CURRENT are not modified. Use as

: <name>
   ...body of new definition...
;

Pronunciation: "colon"
Attributes: D

; ( -- )

Marks the end of a colon definition and enters the execution mode. Checks the stack to make sure that no extra items were placed on or removed from the data stack during compilation of the definition. SMUDGEs the header created by : so that the new word can be found in the dictionary. Compiles code to cause control to be passed to the calling word when the definition is later executed. If locals were used in the definition, the code compiled by ; also removes the local variables from the return stack.
Pronunciation: "semicolon"
Attributes: C, I

< ( n1\n2 -- flag )

Flag is TRUE if n1 is less than n2 and FALSE otherwise.
Pronunciation: "less-than"

<# ( -- )

Prepares for pictured numeric output by initializing the headerless user variable #PTR to be equal to PAD. #PTR points to the current character position in the pictured numeric output, which starts 1 byte below PAD and builds towards low memory.
Pronunciation: "less-number-sign"
Attributes: S

< = ( n1\n2 -- flag )

Flag is TRUE if n1 is less than or equal to n2 and FALSE otherwise.
Pronunciation: "less-than-or-equal"

<> ( w1\w2 -- flag )

Flag is TRUE if w1 is not equal to w2 and FALSE otherwise.
Pronunciation: "not-equal"

<DBUILDS ( <name> -- )

Used in a high level defining word to mark the beginning of the specification of the action taken when a child word is defined. Removes <name> from the input stream and creates a header for <name> in the dictionary. Sets the HAS.PFA bit in the header to indicate that <name> has a parameter field. Use as:

: <namex>
  <DBUILDS   code to set up child's parameter field
  DOES>      run time action
;

where <namex> is referred to as a "defining word". Executing the statement

<namex> <child's.name>

defines the child word. The code after <DBUILDS specifies the action to be taken while defining the child word. This usually involves allotting and/or initializing the parameter field of the child. The "D" in <DBUILDS stands for "definitions area"; the parameter field is located at the next available location in the definitions area pointed to by DP. Thus the words ALLOT and , (comma) (as opposed to VALLOT and V,) should be used after <DBUILDS to reserve and initialize locations in the child's parameter field. Use <DBUILDS to define child words whose parameter fields are to be in non-modifiable write-protected memory once the application program is finished. Restrictions: LOCALS{ } cannot be used between <DBUILDS and DOES>. If you need to use local variables to perform the building action, define and call a subsidiary word that performs the action.

Example of use: a version of CONSTANT could be defined using <DBUILDS:

: MYCONSTANT    ( n <name> -- )
  <DBUILDS   ,
  DOES>      @
;

MYCONSTANT is a defining word. To define a child word named THIS.CON initialized to the value 1234 execute

1234 MYCONSTANT  THIS.CON

When MYCONSTANT executes, it initializes the first 2 bytes in the child's parameter field to 1234 and increments DP by 2. Executing THIS.CON places on the stack the value stored at the extended pfa.

See also DOES>
Pronunciation: "d-builds"
Attributes: D

<VBUILDS ( -- )

Used in a high level defining word to mark the beginning of the specification of the action taken when a child word is defined. Removes <name> from the input stream and creates a header for <name> in the dictionary. Sets the HAS.PFA bit in the header to indicate that <name> has a parameter field. Use as:

: <namex>
   <VBUILDS    code to set up child's parameter field
   DOES>     run time action
;

where <namex> is referred to as a "defining word". Executing the statement

<namex>  <child's.name>

defines the child word. The code after <VBUILDS specifies the action to be taken while defining the child word. This usually involves allotting and/or initializing the parameter field of the child. The "V" in <VBUILDS stands for "variable area"; the parameter field is located at the next available location in the variable area. Thus the words VALLOT and V, (as opposed to ALLOT and ,) should be used after <VBUILDS to reserve and initialize locations in the child's parameter field. Use <VBUILDS to define child words whose parameter fields must always be in modifiable non-write-protected memory, unlike <DBUILDS. Restrictions: LOCALS{ } cannot be used between <VBUILDS and DOES>. If you need to use local variables to perform the building action, define and call a subsidiary word that performs the action.

Example of use: a version of VARIABLE that initializes the variable's contents could be defined using <VBUILDS as,

: INITIALIZED.VAR    ( n <name> -- )
   <VBUILDS    V,
   DOES>
;

INITIALIZED.VAR is a defining word. To define a child word named MYVAR initialized to the value 1234 execute

1234 INITIALIZED.VAR  MYVAR

When INITIALIZED.VAR executes, it initializes the first 2 bytes in the child's parameter field to 1234 and increments VP by 2. Executing MYVAR leaves the extended pfa on the stack (see DOES>) and a fetch from this address will return the value 1234.
Pronunciation: "v-builds"
Attributes: D

= ( w1\w2 -- flag )

Flag is TRUE if w1 is equal to w2 and FALSE otherwise.
Pronunciation: "equals"

> ( n1\n2 -- flag )

Flag is TRUE if n1 is greater than n2 and FALSE otherwise.
Pronunciation: "greater-than"

>< ( w1 -- w2 | w2 has upper and lower bytes of w1 swapped )

Swaps the two bytes of the top data stack cell.
Pronunciation: "swap-bytes"

>= ( n1\n2 -- flag )

Flag is TRUE if n1 is greater than or equal to n2 and FALSE otherwise.
Pronunciation: "greater-than-or-equal"

>ASSM ( -- )

Executes ASSEMBLER so that assembler mnemonics can be found in the dictionary, and enters execution mode. Normally used to compile in-line assembly code into a high level FORTH definition, or to return to assembly after using >FORTH in a CODE definition.

See also CODE, END.CODE, >FORTH
Pronunciation: "to-assembly"
Attributes: I

>DEGREES ( r1 -- r2 )

Converts r1 in radians into r2 in degrees.
Pronunciation: "to-degrees"
Attributes: S

>FORTH ( -- )

Sets vocabulary equal to FORTH and enters compilation mode. Normally used to compile high level FORTH words into an assembly CODE definition, or to return to high level after using >ASSM to assemble in-line code.

See also >ASSM, CODE, END.CODE
Pronunciation: "to-forth"

>IN ( -- xaddr )

User variable that contains the offset from the start of the current input stream to the next character to be parsed. The contents of >IN may range from 0 to the number of characters in the input stream.

See also QUERY, WORD
Pronunciation: "to-in"
Attributes: U

>R ( w -- )

Return Stack: ( R: – w )

Transfers the top cell on the data stack to the return stack.
Pronunciation: "to-r"
Attributes: C

>RADIANS ( r1 -- r2 )

Converts r1 in degrees into r2 in radians.
Pronunciation: "to-radians"
Attributes: S

? ( xaddr -- )

Prints the integer contents of xaddr.
Pronunciation: "question"
Attributes: S

?ARRAY.SIZE ( array.xpfa -- d | d = number of elements in array )

Returns the number of elements d (not the number of bytes!) in the array or matrix designated by array.xpfa. 0\0 is returned for undimensioned arrays and matrices.
Pronunciation: "question-array-size"

?DETERMINANT ( matrix.xpfa\n -- r | n = sign, r = determinant )

Calculates the determinant r of an LU decomposed matrix specified by matrix.xpfa given the sign of the determinant n. May be used after LU.DECOMPOSITION executes. LU.DECOMPOSITION puts the source matrix in the proper form and calculates n. ?DETERMINANT then returns the value of the determinant of the matrix.

Attributes: S

?DIM.MATRIX ( matrix.xpfa -- #rows\#cols )

Returns the number of rows and columns in the specified matrix. If DEBUG is ON, ABORTs if matrix.xpfa is undimensioned or is not a matrix.
Pronunciation: "question-dim-matrix"

?DIMENSIONS ( array.xpfa -- [u1\u2\...uN\N\n ] or [0\0] | N=#dim, n=bytes/element )

Returns the number of elements u1, u2, …uN in each dimension under the number of dimensions N under the number of bytes per element n for the array or matrix designated by array.xpfa. Returns 0\0 if the array is undimensioned.
Pronunciation: "question-dimensions"

?DUP ( w -- [w\w] or [0] )

Duplicates the top cell of the data stack if it is non-zero.
Pronunciation: "question-dupe"

?GET ( xresource -- flag | flag is true if resource is available )

Checks the resource variable xresource. If the resource is available (i.e., if it contains 0\0 or the current task's xtask.id), ?GET claims the resource by storing the current task's xtask.id in xresource, and returns a true flag. Otherwise, ?GET returns a false flag. Does not execute PAUSE. To ensure that the state of the resource is correctly determined, ?GET disables interrupts for 27 to 57 cycles (6.75 to 14.25 microseconds).

See also GET, RELEASE, and RESOURCE.VARIABLE:
Pronunciation: "question-get"

?HANDLE.SIZE ( xhandle -- +d )

+d is the number of heap bytes allocated to the heap item associated with xhandle. An unchecked error occurs if xhandle is not a valid heap handle.
Pronunciation: "question-handle-size"

?HAS.PFA ( xnfa -- flag )

Returns a TRUE flag if the word referenced by xnfa has a parameter field address.
Pronunciation: "question-has-p-f-a"

?IMMEDIATE ( xnfa -- flag )

Returns a TRUE flag if the word referenced by xnfa is an immediate word.
Pronunciation: "question-immediate"

?KEY ( -- flag )

Returns a flag indicating receipt of a character. If flag is TRUE, a character has been received; otherwise, no character has been received. Depending on the value in SERIAL.ACCESS, may execute SERIAL RELEASE and SERIAL GET.

See also GET, RELEASE and SERIAL.ACCESS

?KEY is a vectored routine that executes the routine whose xcfa is stored in the user variable U?KEY. Thus the programmer may install a different routine to tailor the behavior of ?KEY to the application's needs. For example, ?KEY could access a serial port other than that on the 68HC11 chip, or different tasks could use different ?KEY routines.

See also ?KEY1 and ?KEY2
Pronunciation: "question-key"
Attributes: M, U

?KEY1 ( -- flag )

Returns a flag indicating whether a character has been received on the primary serial port (serial1) associated with the 68HC11's on-chip hardware UART. If a character has been received a TRUE flag is returned; otherwise a FALSE flag is returned. ?KEY1 is the default ?KEY routine installed in the U?KEY user variable after the special cleanup mode is invoked, or if SERIAL1.AT.STARTUP has been executed. If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, ?KEY1 does not GET or RELEASE the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, ?KEY1 GETs and RELEASEs the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, ?KEY1 GETs but does not RELEASE the SERIAL1.RESOURCE.

See also SERIAL.ACCESS, ?KEY, U?KEY, ?KEY2
Pronunciation: "question-key-one"
Attributes: M

?KEY2 ( -- flag )

Returns a flag indicating whether a character has been received on the secondary serial port (serial2). The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). If one or more characters are present in the serial2 input buffer a TRUE flag is returned; otherwise a FALSE flag is returned. ?KEY2 can be made the default ?KEY routine installed in the U?KEY user variable after each reset or restart by executing SERIAL2.AT.STARTUP. If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, ?KEY2 does not GET or RELEASE the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, ?KEY2 GETs and RELEASEs the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, ?KEY2 GETs but does not RELEASE the SERIAL2.RESOURCE.

See also SERIAL.ACCESS, ?KEY, U?KEY, KEY1
Pronunciation: "question-key-two"
Attributes: M

?KEYPAD ( -- [n\TRUE] or [FALSE] | 0 < = n < = 39 )

Scans keypad or touchscreen having up to 8 rows and 5 columns. If a key is being depressed, PAUSEs and waits until the key is released, then returns the key number under a true flag. If no key is depressed, returns a false flag. Consult the KEYPAD glossary entry for a detailed description of keypad orientation. Disables interrupts for 12 µseconds each time a row is scanned.

See also ?KEYPRESS and KEYPAD
Pronunciation: "question-keypad"

?KEYPRESS ( -- [n\TRUE] or [FALSE] | 0 < = n < = 39 )

Scans keypad or touchscreen having up to 8 rows and 5 columns. If a key is being depressed, returns the key number under a true flag; unlike ?KEYPAD, ?KEYPRESS does not wait for the key to be released. If no key is depressed, returns a false flag. Consult the KEYPAD glossary entry for a detailed description of keypad orientation. Disables interrupts for 12 microseconds each time a row is scanned.

See also ?KEYPAD and KEYPAD
Pronunciation: "question-keypress"

?MATRIX.SIZE ( matrix.xpfa -- d | d = number of elements in matrix )

Returns the number of elements d (not the number of bytes!) in the specified matrix. If DEBUG is ON, ABORTs if matrix.xpfa is undimensioned or is not a matrix. If DEBUG is OFF, no error checking is performed, and d is indeterminant if matrix is not dimensioned.
Pronunciation: "question-matrix-size"

?RECEIVE ( xmailbox -- [wd\true] or [false] | wd = received message )

If xmailbox is empty (i.e., if it contains 0\0), returns a false flag. If xmailbox contains a message (i.e., if it does not contain 0\0), fetches the contents of xmailbox wd and stores a 0\0 into xmailbox to indicate that the message has been received and that the mailbox is now empty. Leaves the message wd on the stack under a true flag. Does not execute PAUSE. To ensure that the state of the mailbox is correctly determined, ?RECEIVE disables interrupts for 26 to 61 cycles (6.5 to 15.25 microseconds).

See also SEND, RECEIVE, and MAILBOX:
Pronunciation: "question-receive"

?SEND ( wd\xmailbox -- flag | flag is true if message was sent )

If the mailbox with extended address xmailbox is empty (i.e., contains 0\0), stores the 32-bit message wd in xmailbox and returns a true flag. If xmailbox is not empty, drops wd and returns a false flag. Does not execute PAUSE. The message wd can be any 32-bit quantity except 0\0. For example, the message can be an xaddress that points to a block of data. To ensure that the state of the mailbox is correctly determined, ?SEND disables interrupts for 16 to 50 cycles (4 to 12.5 microseconds).

See also SEND, RECEIVE, and MAILBOX:
Pronunciation: "question-send"

@ ( xaddr -- w )

Fetches a 16-bit number from the memory location specified by xaddr. The high order byte is taken from xaddr and the low order byte from xaddr+1. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "fetch"

A/D8.MULTIPLE ( xaddr\u1\u2\n -- | u1=timing parameter, u2 = #samples, n = channel# )

Acquires u2 samples from the 8 bit analog to digital (A/D) converter in the 68HC11 and stores the samples as sequential unsigned 8 bit values starting at the specified xaddr. n specifies the channel number of the A/D (0 < = n < = 7). To ensure proper operation in a multitasking environment, this routine executes A/D8.RESOURCE GET before reading the A/D and A/D8.RESOURCE RELEASE before terminating. If the specified xaddr is in common memory, the first sample is taken after 86 microseconds and subsequent samples are taken every (10+2.5*u1) microseconds, where u1 is the specified timing parameter passed to this routine. If the specified xaddr is in paged memory, the first sample is taken after 81 microseconds and subsequent samples are taken every (32.5+2.5*u1) microseconds. Of course, the operation of interrupts (including timesliced multitasking) will affect these sampling times. For a faster version suitable for non-multitasking applications, use (A/D8.MULTIPLE).

See also A/D8.SAMPLE, (A/D8.SAMPLE), and A/D8.ON
Pronunciation: "A-to-D-eight-multiple"
Attributes: M

A/D8.OFF ( -- )

Turns off the 68HC11's on-chip 8 bit analog to digital (A/D) converter by clearing the ADPU bit in the processor's OPTION register. The 8 bit A/D is initialized to the off state upon every reset or restart.

See also A/D8.ON
Pronunciation: "A-to-D-eight-off"

A/D8.ON ( -- )

Turns on the 68HC11's on-chip 8 bit analog to digital (A/D) converter by setting the ADPU bit in the processor's OPTION register, and waits 100 microseconds for the A/D to stabilize. Also initializes A/D8.RESOURCE to 0\0. This routine must be executed after a reset or restart before using the 8 bit A/D.

See also A/D8.OFF
Pronunciation: "A-to-D-eight-on"

A/D8.RESOURCE ( -- xaddr )

A resource variable associated with the 8 bit analog to digital (A/D8) converter. Should be accessed only by the words GET ?GET and RELEASE. Initialized to 0\0 by A/D8.ON and at each reset or restart. A/D8.RESOURCE is automatically invoked by many of the A/D8 device drivers.

See also RESOURCE.VARIABLE:
Pronunciation: "A-to-D-eight-resource"

A/D8.SAMPLE ( n -- byte | n = channel# )

Acquires and places on the stack a single sample byte from the 8 bit analog to digital (A/D) converter in the 68HC11. n specifies the channel number of the A/D (0 ≤ n ≤ 7). To ensure proper operation in a multitasking environment, this routine executes A/D8.RESOURCE GET before reading the A/D and A/D8.RESOURCE RELEASE before terminating. This routine executes in 93 microseconds. For a faster version suitable for non-multitasking applications,

See also (A/D8.SAMPLE)

See also (A/D8.MULTIPLE), A/D8.MULTIPLE, and A/D8.ON
Pronunciation: "A-to-D-eight-sample"

ABORT ( [...] -- )

Return Stack: ( R: […] – )

If the CUSTOM.ABORT flag is true, executes the abort routine whose xcfa is stored in the user variable UABORT, and then returns to the routine that called ABORT. If CUSTOM.ABORT is false, executes the default routine (ABORT) which clears the data and return stacks, sets the page to the default page (0), and executes FORTH DEFINITIONS to set CONTEXT and CURRENT equal to FORTH. If an autostart vector has been installed (ie AUTOSTART), (ABORT) executes the specified routine; otherwise it executes QUIT which sets the compilation mode and enters the interpreter. If R0 and S0 aren't in common RAM, a COLD restart is initiated.

ABORT" ( flag -- )

Compile Time: ( <text> – )

If flag is true, prints the <text> string between ABORT" and the terminating " and then executes ABORT. If flag is false, drops flag and continue execution. Useful for error detection and reporting.
Pronunciation: "abort-quote"
Attributes: C, I, M

ABS ( n1 -- +n2 | +n2 = absolute value of n1 )

Replace n1 with its absolute value +n2. If n1 is positive, +n2 = n1. If n1 is negative, +n2 is the negative of n1.
Pronunciation: "abs"

ACTIVATE ( xcfa\xtask.id -- )

Sets up the routine specified by xcfa as the action word of the task whose task identifier (STATUS xaddress) is xtask.id, and leaves the specified task AWAKE so that it will be entered on the next pass through the round robin task list. ACTIVATE assumes that the specified task has already been added to the task list by BUILD.TASK or BUILD.STANDARD.TASK. The task's action word is typically either an infinite loop or a finite routine that ends with a HALT instruction (which is itself an infinite loop). ACTIVATE buries a call to HALT in the return stack frame to ensure graceful termination of a finite activation routine. If cooperative multitasking is used exclusively (i.e., if the timeslicer is not used), then the loop of the action word must contain at least one PAUSE statement (or invoke a word that in turn executes PAUSE). Otherwise, no task switching occurs. If timeslicing is used, incorporation of PAUSE statements in the loop of the action word is optional. The typical form of an action word is:

: <action.name>
   words to be executed once
   BEGIN
      words to be executed infinitely
      PAUSE
      words to be executed infinitely
   AGAIN
;

or:

: <action.name>
   words to be executed
   PAUSE
   words to be executed
   HALT
;

For example, if a task has been defined with

TASK: <task.name>

and built using BUILD.TASK or BUILD.STANDARD.TASK, it can be activated by executing

CFA.FOR <action.name>  <task.name>  ACTIVATE

ADDR-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for one 16 bit address field in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "address"
Attributes: D

ADDR: ( <name> -- )

ADDR: is a synonym for INTEGER: . It defines a 16-bit self-fetching variable. ADDR: is meant to hold a 16-bit address. Also see the glossary entry for INTEGER:
Pronunciation: "address-colon"
Attributes: D

ADDRS-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 16 bit addresses in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "addresses"
Attributes: D

AGAIN ( -- )

AGAIN is used within a colon definition to mark the end of an infinite loop structure as:

BEGIN
   <words to be iterated>
AGAIN

The words between BEGIN and AGAIN are executed indefinitely. AGAIN is equivalent to FALSE UNTIL. An error is issued if BEGIN and AGAIN are not properly paired inside a definition.

Attributes: C, I

ALL.COLUMNS.SCALED ( matrix.xpfa1\[row#1\-1] or [-1\col#1]\ matrix.xpfa2 -- )

Scales each column of the matrix specified by matrix.xpfa1 by dividing each element in the column by the amount designated in the scaler row/col specified by [row#1\-1] or [-1\col#1]\ matrix.xpfa2 which must have the same number of elements as the number of columns of the matrix. The scaler row/col should not be part of the matrix being scaled. That is, matrix.xpfa1 may not equal matrix.xpfa2.

Attributes: S

ALL.ROWS.SCALED ( matrix.xpfa1\[row#\-1] or [-1\col#]\ matrix.xpfa2 -- )

Scales each row of the matrix specified by matrix.xpfa1 by dividing each element in the row by the amount designated in the scaler row/col specified by [row#\-1] or [-1\col#]\ matrix.xpfa2 which must have the same number of elements as the number of rows of the matrix. The scaler row/col should not be part of the matrix being scaled. That is, matrix.xpfa1 may not equal matrix.xpfa2.

Attributes: S

ALL.TO.FLASH ( -- )

If the standard map is already set, ALL.TO.FLASH simply executes SAVE. If the download map is set, this command copies pages 4, 5, and 6 to flash, then sets the standard map and calls SAVE. This function ensures that an application program up to 96 Kbytes long compiled on pages 4, 5, and 6 is properly transferred to flash after a download. In the event of a crash or COLD restart during the debugging process, RESTORE can be used to regain access to the compiled code to continue debugging. USAGE: When paired with the ENABLE.DOWNLOAD command, this function simplifies the loading of a Forth program. Place the ENABLE.DOWNLOAD command at the top of the first file to be loaded (before the file’s memory map and ANEW statements), and place ALL.TO.FLASH at the end of the last file to be loaded. This ensures proper compilation of code into RAM pages 4, 5 and 6 in the download map, followed by transfer to flash and setting of the standard map. It is also possible to put ENABLE.DOWNLOAD at the top of each source code file, and ALL.TO.FLASH at the bottom of each source file. This technique ensures proper compilation of any given source code file during the development process. Of course, this command may also be typed at the QED-Forth prompt after code is downloaded.

See also ENABLE.DOWNLOAD

ALLOCATED ( u\xpfa -- | u is heap item size in bytes )

Allocates u bytes of heap memory and associates it with the item having the specified parameter field address xpfa. The xpfa is typically associated with a word defined by H.INSTANCE:. Typical use:

size.of.heap.item  H.INSTANCE:  <name>
SIZE.OF <name>  ' <name> ALLOCATED

or:

size.of.heap.item  ' <name> ALLOCATED

See H.INSTANCE: and SIZE.OF.

ALLOT ( n -- )

Reserves n bytes in the dictionary by incrementing the definitions pointer DP by n. An error occurs if the ALLOT operation causes DP to be incremented across the boundary between 0x7FFF (the last valid address in a given page) and 0x8000 (the start of the register area).

AND ( w1\w2 -- w3 )

Performs a logical bit-wise 'and' of two 16 bit numbers w1 and w2 to produce the result w3.

ANEW ( <name> -- )

Tries to find <name> in the CURRENT vocabulary. If <name> is not found or was not created by ANEW, then creates <name>. If <name> is found, executes <name> which resets the variable pointer VP to the value it had when ANEW <name> was first executed, then FORGETs all words defined after <name> was created; this resets DP and NP to the values they had when ANEW <name> was first executed. ANEW should be used to avoid redundancy when reloading code during debugging. Note that heap items associated with forgotten words are not released by ANEW and should be handled by the programmer using ON.FORGET.

See also FORGET and ON.FORGET

ARRAY.PF ( -- u | u = size of an array parameter field )

Places on the stack the number of bytes in an array parameter field based on the current value of MAX#DIMENSIONS. Typically used to define a stack-based temporary array within a definition; temporary arrays defined in this manner preserve re-entrancy (read the chapter on Designing Re-entrant Code in the Software Manual). For example:

: ARRAY.FUNCTION
   LOCALS{ .... | x&temp.array.pfa }
   ARRAY.PF PF.STACK.FRAME   TO  x&temp.array.pfa
   10 1 6 x&temp.array.pfa DIMENSIONED   \ dimension
   ....      \ use the temp array
   x&temp.array.pfa DELETED   \ delete from heap
   ARRAY.PF FRAME.DROP   \ drop temp pf off stack
;

See MATRIX.PF, PF.STACK.FRAME and FRAME.DROP
Pronunciation: "array-p-f"

ARRAY: ( <name> -- )

Removes <name> from input stream and defines <name> as an array. Allots and clears a parameter field for <name> in the variable area. When executed, <name> returns the extended element address given the indices; its stack picture is:

( indices -- xaddr )

The element xaddress is also returned by the command

indices ' <name> []

ARRAY: does not allocate heap space or dimension the array;

See also DIMENSIONED
Pronunciation: "array-colon"
Attributes: D

ASCII ( <name> -- char )

Removes <name> from the input stream and converts its first character to its ASCII value char. In execution mode the ascii value is left on the stack. In compilation mode the ascii code is compiled as a literal into the current definition.

Attributes: I

ASK.FNUMBER ( <text> -- [r\-1] or [0] )

Inputs a character string <text> to the PAD buffer, terminating when CHARS/LINE characters are received or a carriage return is received, whichever comes first. Leaves <text> as a counted string at PAD and, ignoring leading blanks, attempts to convert the <text> string to a valid floating point number. If <text> is an ascii representation of a valid integer or double number or floating point number, the equivalent floating point representation r is left on the stack under a true flag; otherwise, a false flag is left on the stack.

See also ASK.NUMBER and NEXT.NUMBER
Pronunciation: "ask-f-number"
Attributes: M, S

ASK.NUMBER ( <text> -- [n\1] or [d\2] or [0] )

Inputs a character string <text> to the PAD buffer, terminating when CHARS/LINE characters are received or a carriage return is received, whichever comes first. Leaves <text> as a counted string at PAD and, ignoring leading blanks, attempts to convert the <text> string to a single or double number. If the string is converted to a 16-bit integer n, leaves n under a 1 flag. If the string cannot be represented as a 16-bit integer but is a valid 32-bit double number d, leaves d on the stack under a 2 flag. Conversion is performed in the current number base unless the number starts with 0x or 0X, in which case hexadecimal base is used. Leaves a 0 flag on the stack if the <text> string cannot be converted to a valid integer.

See also ASK.FNUMBER and NEXT.NUMBER

Attributes: M, S

ASLEEP ( -- 1 )

A constant that places the value 1 on the stack. When stored into a task's STATUS user variable, indicates to the multitasking executive that the task is asleep and cannot be entered.

ASSEMBLER ( -- )

Sets CONTEXT equal to the assembler vocabulary's xhandle so that the assembler vocabulary is the first vocabulary searched during dictionary searches.

ATTACH ( xcfa\n -- | n = interrupt identity number )

Posts an interrupt handler routine specified by xcfa for the interrupt with identity number n (e.g., OC1.ID, OC2.ID, etc.) Compiles an 8-byte code sequence at the EEPROM location associated with the specified interrupt. When the interrupt is serviced, the code at xcfa will be executed. The xcfa can be on any page. If coded in high level, the interrupt handler routine should end with a ; and if coded in assembly should end with an RTS (as opposed to an RTI).

AUTOSTART ( xcfa -- )

Compiles a 6-byte sequence into the EEPROM in the 68HC11. On subsequent restarts and ABORTs, the routine having the specified xcfa will be executed. This allows a finished application to be automatically entered upon power up and resets. CAUTION: If your application is to be put into production and replicated, it is recommended that you use the PRIORITY.AUTOSTART function which stores the 6-byte autostart sequence in flash memory.

Implementation detail: At location 0xAE00 in EEPROM, AUTOSTART writes the pattern 1357 followed by the four byte xcfa. To undo the effects of this command and return to the default startup action, use NO.AUTOSTART. To recover from the installation of a buggy autostart routine, use the special cleanup mode. (See PRIORITY.AUTOSTART, and consult the "Interrupts, Register Initializations, and Autostarting" chapter in the Software Manual.)

AWAKE ( -- 0 )

A constant that places the value 0 on the stack. When stored into a task's STATUS user variable, indicates to the multitasking executive that the task is awake and may be entered.

AXE ( <name> -- )

If <name> is found in the CURRENT vocabulary, removes its header and compacts the vocabulary, but leaves the definition (i.e., the code field) of <name> intact. Once a word's header has been AXEd it can no longer be found in the dictionary. AXE is useful for conserving memory space in the names area of the dictionary. AXE works properly only if the name area after <name> is a contiguous single-vocabulary linked list in modifiable RAM . An error is issued if <name> is not found or if <name> is on a different page than that returned by LATEST. An unchecked error occurs if words have been defined into vocabularies other than the CURRENT vocabulary since <name> was defined, or if NP has been explicitly moved with an

<xaddr> NP X!

command since <name> was defined.

BACKTRACK ( -- )

Resets >IN to point to the first character of the word in the input stream that was most recently parsed by WORD.

BASE ( -- xaddr )

User variable that contains the current number base (number conversion radix) used for number I/O and numeric conversion. Unchecked error if the contents of BASE are less than 2 or greater than 72.

Attributes: U

BAUD1.AT.STARTUP ( n -- )

Configures the QED Board so that the baud rate of the primary serial port (serial1) supported by the 68HC11's hardware UART will equal the specified standard baud rate upon all subsequent resets and restarts. Standard baud rates for boards clocked at 16 MHz are 150, 300, 600, 1200, 2400, 4800, 9600, and 19200 baud.

Implementation detail: This routine calls INSTALL.REGISTER.INITS which writes into EEPROM the required contents of INIT (=0xB8), the contents of BAUD that corresponds to the specified baud rate, and the contents of OPTION, TMSK2, BPROT that are present when this routine is executed. These values are installed in their respective registers upon each subsequent reset and restart. To undo the effects of this command, execute DEFAULT.REGISTER.INITS or invoke the special cleanup mode.
Pronunciation: "baud-one-at-startup"

BAUD2 ( n -- )

Sets the baud rate of the secondary serial port (serial2) supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). Smooth file transfers can be achieved at up to 4800 baud, but note that the operation of other interrupt service routines may lower the attainable error-free baud rate. The baud rate of serial2 is initialized to 1200 baud by the COLD restart routine.

See also USE.SERIAL2
Pronunciation: "baud-two"

BEEP ( -- )

Emits the bell character, ascii 07, if QUIET is OFF .

BEGIN ( -- )

BEGIN is used within a colon definition to mark the start of a loop structure as:

BEGIN ... UNTIL
BEGIN ... WHILE ... REPEAT
BEGIN ... AGAIN

The words after UNTIL or REPEAT are executed after the loop structure terminates. BEGIN … AGAIN is an infinite loop. An error is issued if BEGIN is not properly paired in a loop structure.

Attributes: C, I

BENCHMARK: ( <name> -- )

Measures and displays the execution time and operations count for the word <name>. The timeslice clock must be running to benchmark a word. This can be accomplished by executing START.TIMESLICER before invoking BENCHMARK:. <name> may be any executable word. Data stack parameters required by <name> should be placed on the stack before calling BENCHMARK:. Typical use:

START.TIMESLICER    \ if timeslicer wasn't already running ...
   \ push necessary stack parameters for <name>
BENCHMARK: <name>

See also (BENCHMARK:)
Pronunciation: "benchmark"
Attributes: M, S

BL ( -- char )

Puts the ascii value for a blank (a space, ascii value 32) on the data stack.
Pronunciation: "b-l"

BLANK ( xaddr\u -- | u = byte count )

The ascii character value for space (32) is stored in each of u consecutive bytes beginning at xaddr. The specified region may cross page boundaries. Does nothing if u = 0.

BLANK.ARRAY ( array.xpfa -- )

Stores an ascii blank (32) into each byte of the specified array.

BLK ( -- xaddr )

A user variable whose contents equal the number of the file block currently being interpreted. Contents of 0 indicate that the input stream is to be taken from the terminal input buffer (TIB). Modified by –>, LOAD and THRU, cleared by QUERY.
Pronunciation: "b-l-k"
Attributes: U

BLOCK ( n -- xaddr | n = block#, xaddr = buffer )

Performs the function of BUFFER which assigns the block specified by n to the buffer starting at xaddr, and then reads the contents of the specified block n from mass memory into its assigned buffer at xaddr. Note that the starting location of the specified block in mass memory is given by 1024*(n + offset) where offset equals the 32-bit contents of the user variable OFFSET.

See also BUFFER

Attributes: M

BOOLEAN ( w -- flag )

Converts a 16-bit integer into a boolean flag. Flag is FALSE (0) if w is 0, otherwise flag is TRUE (-1).

BREAK ( -- )

Sets a software breakpoint when compiled into any function (including assembly language functions). At execution time, BREAK suspends the program flow, saves the machine state and invokes a FORTH-style text interpreter that can be distinguished from the standard interpreter by the BREAK> prompt displayed at the start of each line. Any valid commands may be executed from within the BREAK interpreter. From within the BREAK interpreter, typing a carriage return alone on a line exits the BREAK mode, restores the machine registers to the values they held just before BREAK was entered, and resumes execution of the program that was running when BREAK was entered. The BREAK routine's preservation of the register state and its ability to execute any valid command make it a very powerful debugging tool. BREAK may be compiled into any definition to stop program flow in order to debug or analyze a word at the point where BREAK was called. Once inside BREAK, the stack contents may be displayed (using .S) or altered. Variables and memory locations may be displayed or altered. New words can even be defined and executed. BREAK is called by the trace routine if the variable SINGLE.STEP is set. To single step through some code, compile the code with TRACE ON, then execute the code with DEBUG and SINGLE.STEP ON. After each call, the name of the traced word and the stack picture will be printed, and then the BREAK word will execute, letting you execute FORTH commands. To go to the next "step" in the word being debugged, enter a CR alone on a line. To display the register state after each traced line, execute DUMP.REGISTERS ON. To stop single-stepping but continue tracing, execute the forth command SINGLE.STEP OFF. The trace will continue, but BREAK will not be called again, unless you hit a key. The trace routine enters the BREAK mode when a keystroke is detected at the serial I/O port: if you hit a key, BREAK is called by TRACE, and again, a CR resumes execution. To exit the traced definition completely, execute ABORT (or any illegal command) from within the BREAK interpreter. Any error encountered while in the BREAK routine executes ABORT which places the programmer back into the standard QED-Forth interpreter (unless ABORT has been revectored to perform some other action using CUSTOM.ABORT).

See also DEBUG, TRACE, SINGLE.STEP, DUMP.REGISTERS, and IS.TRACE.ACTION

Attributes: M, S

BUFFER ( n -- xaddr | n = block#, xaddr = buffer )

Returns the extended address xaddr of the first byte of the block buffer assigned to the block specified by n. If the specified block is already in a buffer, writes the buffer's contents to mass memory if the block has been UPDATED, and returns the extended address of the buffer. If the specified block is not already in a buffer, assigns it to a buffer, writing the previous contents of the buffer to mass memory if the previous contents had been UPDATED. BUFFER does not load the buffer with the contents of the specified block (see BLOCK). Note that the starting location of the specified block in mass memory is given by 1024*(n + offset) where offset equals the 32 bit contents of the user variable OFFSET.

Attributes: M

BUFFER.POSITION ( n1\n2 -- n3 | n1 = line#, n2 = char#, n3 = buffer.offset )

Given the specified LCD display line number n1 (0 ≤ n1 < LINES/DISPLAY) and the specified character position in the display line (0 ≤ n2 < CHARS/DISPLAY.LINE), calculates the offset n3 of the specified position relative to the extended base address returned by DISPLAY.BUFFER. Clamps n3 to ensure that the buffer.offset is not greater than the size of the buffer. Note that for a graphics-style display the line# n1 is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, n1 corresponds to the character line#; in graphics mode, n1 corresponds to the pixel line#.

See also LINES/DISPLAY

BUFFER>SPI ( xaddr\+n -- )

Writes to the SPI the contents of the buffer specified by xaddr and +n, where xaddr is the starting address, and +n is the number of bytes (0 ≤ +n ≤ 32,768). The buffer must not cross a page boundary. This routine does not GET or RELEASE the SPI.RESOURCE, nor does it modify the configuration of the SPI or activate any chip selects. If required, these additional functions must be performed by the calling program. This routine is optimized for speed, and executes at 9 microseconds per byte.

BUILD.STANDARD.TASK ( xaddr1\xaddr2\xaddr3\xtask.id -- |

      xaddr1=xheap.start, xaddr2=xheap.end, xaddr3=VP )

Builds a task with a specified heap and variable area and no compilation privileges. The task's stacks, user area, PAD, POCKET, and TIB are assigned to a 1Kbyte block of common RAM starting at xtask.id (the base of the task's user area). The task is appended to the round-robin task list and left ASLEEP running the default action word HALT. xaddr1 is the extended heap starting address, and xaddr2 is the extended heap end address. BUILD.STANDARD.TASK passes these to IS.HEAP which initializes the heap accordingly. xaddr3 specifies the start of the variable area for the task, and xtask.id is the task identifier xaddress (also called the task's STATUS address or the base of its user area.) DP and NP are set to xaddress 0\0 in ROM so that the task cannot compile new words (it can, however, interpret and execute previously defined words). The 256-byte user area of the parent task (i.e., the task that is active when this command executes) is copied to create the new task's user area, so the parent's configuration is initially "inherited" by the new task. This implies that the new task has access to all the words in the parent's dictionary. The variables that control the memory map of the new task are set so that R0 = xtask.id + 0x400, S0 = xtask.id + 0x300, (both stacks have 1/4K space and grow downward in memory), TIB extends upward for 94 bytes starting at xtask.id + 0x180, POCKET extends upward for 32 bytes starting at xtask.id + 0x1E0, and PAD extends upward for 82 bytes and downward for 36 bytes starting at xtask.id + 124H. (Implementation detail: The multitasker uses the 2 bytes below TIB to hold a C stack pointer.) To initialize CURRENT.HEAP without modifying the heap control variables, pass BUILD.STANDARD.TASK a heap start xaddress that is equal to the heap end xaddress (see IS.HEAP).

BUILD.TASK ( xheap.start\xheap.end\xvp\xdp\xnp\xtib\xpad\xpocket\xr0\xs0\xtask\n -- )

Builds a task with a specified memory map. Appends the task to the round-robin task list and leaves it ASLEEP running the default action word HALT. The stack picture above uses non-standard symbols that are more descriptive than a long list of xaddr items.

All but the last item on the stack are extended addresses (xaddr). The last item n is the integer size of the user area. The first n bytes of the user area of the parent task (i.e., the task that is active when this command executes) are copied to create the new task's user area, so the parent's configuration is initially "inherited" by the new task. This implies that the new task has access to all the words in the parent's dictionary because the values in the new task's CONTEXT and CURRENT user variables have been copied from the parent.

The variables that control the memory map of the new task are set according to the parameters passed to BUILD.TASK. xheap.start\xheap.end are passed to IS.HEAP which initializes the heap accordingly. To initialize CURRENT.HEAP without modifying the heap control variables, pass BUILD.STANDARD.TASK a heap start xaddress that is equal to the heap end xaddress; (see IS.HEAP). xvp specifies the contents of VP in the new task's user area, xdp specifies DP, xnp specifies NP, xtib specifies the contents of UTIB, xpad specifies the contents of UPAD, xpocket specifies the contents of UPOCKET, xr0 specifies R0 which positions the return stack, and xs0 specifies S0 which positions the data stack. xtask.id is the base address of the user area; it is the xaddress placed on the stack when the task's name is invoked. xr0, xs0, and xtask.id must be in common ram. The user area grows upward in memory, and stacks grow downward. If the new task ever calls WORD or interprets input, a POCKET buffer must be allocated and must be in the common RAM. The heap, VP, DP, NP, TIB, and PAD can be anywhere in memory. BUILD.TASK gives the programmer complete flexibility in allocating memory resources to a task. Some tasks might not need all of these memory areas; in this case, default xaddresses in ROM such as 0\0 can be used to initialize the unneeded memory pointers. The minimum required resources for a task are the first 6 bytes of the user area (STATUS, NEXT.TASK, and RP.SAVE) and a return stack. At the other end of the complexity scale, tasks that can compile new definitions and perform math, I/O and heap operations need to allocate all of the memory areas. Passing values for xvp and xdp in RAM allows compilation of new definitions and the task could subsequently have a private dictionary segment that is not accessible to other tasks. (However, note that concurrent compilation by multiple tasks is discouraged, as some compilation variables such as local variable save locations are not in task-private memory). An error is issued if xtask.id, xr0 or xs0 is not in the common RAM.

See also BUILD.STANDARD.TASK

BYTE-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for a single byte field in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "byte"
Attributes: D

BYTES-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 bytes in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "bytes"
Attributes: D

BYTES>DISPLAY ( xaddr\+n\addr -- )

Sends +n bytes of data starting at xaddr to the graphics display specified by addr. This is a low-level primitive that is typically not useful to the end user.

C! ( byte\xaddr -- )

Stores byte at xaddr.
Pronunciation: "c-store"

C, ( byte -- )

Stores byte at the next available location in the definitions area and increments the definitions pointer DP by 1. An error occurs if byte is not correctly stored; e.g. if DP does not point to RAM. An error occurs if the C, operation causes DP to be incremented across the boundary between 0x7FFF (the last valid address in a given page) and 0x8000 (the start of the register area).
Pronunciation: "c-comma"

C@ ( xaddr -- byte )

Fetches the byte stored at xaddr.
Pronunciation: "c-fetch"

CALC.CHECKSUM ( xaddr\+n -- checksum | n MUST be even )

Calculates a 16-bit checksum for the buffer specified by xaddr and +n, where xaddr is the starting address, and +n is the number of bytes (0 ≤ +n ≤ 32,768). The buffer must not cross a page boundary, and n must be an even number of bytes. The checksum is calculated by initializing a 16-bit accumulator to zero, then adding in turn each 2-byte number in the buffer to the accumulator; the checksum is the final value of the accumulator. Using this routine provides a method of checking whether the contents of an area of memory have changed since a prior checksum was calculated. This routine is optimized for speed, and executes at less than 3 microseconds per byte.

CALL ( <name> -- )

Removes <name> from the input stream and compiles a call to <name> into the current definition, where <name> is the name of an executable FORTH or assembly coded routine. Typically used in an assembly coded definition. Consult the Assembler chapter of the Software Manual for examples of use.

CASE ( n -- n )

Used inside a colon definition to mark the beginning of a CASE statement which implements a multi-decision control structure. Use as:

n1 CASE
   n2 OF words to be executed if n1 = n2       ENDOF
   n3 OF words to be executed if n1 = n3       ENDOF
    n4 OF words to be executed if n1 = n4       ENDOF
   words to be executed if n1 does not equal n2 or n3 or n4
ENDCASE

An error is issued if CASE and ENDCASE are not properly paired in a definition.

See also ENDCASE, OF, ENDOF, RANGE.OF, and URANGE.OF

Attributes: C, I

CFA.FOR ( -- xcfa )

Compile Time: ( <name> – )

Removes <name> from the input stream and returns <name>'s extended code field address xcfa. xcfa is the first byte of executable code associated with <name>'s definition. If in execution mode, leaves the xcfa on the stack. If in compilation mode, compiles the xcfa as a 2-cell literal in the current definition; the xcfa is pushed to the stack when the definition later executes. An error occurs if no <name> is given or if <name> cannot be found in the dictionary.
Pronunciation: "c-f-a-for"
Attributes: I

CFA.PTR ( xnfa -- xaddr )

Given the extended name field address xnfa of a header in the dictionary, returns the xaddr in the header that contains the 3-byte code field address associated with the header. The page of the code field is a single byte stored at xaddr, and the address of the code field is a 16-bit address stored at xaddr+1.

See also NFA.FOR
Pronunciation: "c-f-a-pointer"

CFA>NAME ( xcfa -- )

Prints the name of the word associated with the specified extended code field address xcfa. Useful for error diagnostics to print the name of the word in which an error occurs. The name is printed as ?NAME? if no name corresponding to xcfa is found in the dictionary.
Pronunciation: "c-f-a-to-name"

CFA>NFA ( xcfa -- [xnfa] or [0\0] )

Given the extended code field address xcfa of a word in the dictionary, searches the dictionary and returns the extended name field address xnfa of the word. If the name associated with xcfa cannot be found in the dictionary, returns 0\0. xcfa is the first byte of executable machine code associated with the definition, and xnfa is the count byte of the word's header.

See also CFA.FOR, ID. and NFA.FOR
Pronunciation: "c-f-a-to-n-f-a"

CFA>PFA ( xcfa -- [xpfa] or [0\0] )

Given the extended code field address xcfa of a word in the dictionary, searches the dictionary and returns the extended parameter field address xpfa of the word. If the name associated with xcfa cannot be found in the dictionary or if it does not have a parameter field, returns 0\0.

See also CFA.FOR and '
Pronunciation: "c-f-a-to-p-f-a"

CHANGE.BITS ( byte1\byte2\xaddr -- | byte1 = data; byte2 = mask )

At the byte specified by xaddr, modifies the bits specified by 1's in byte2 to have the values indicated by the corresponding bits in byte1. In other words, byte2 serves as a mask which specifies the bits at xaddr that are to be modified, and byte1 provides the data which is written to the modified bits. Disables interrupts for 16 cycles (4 microseconds) to ensure an uninterrupted read/modify/write operation.

See also (CHANGE.BITS)

CHAR>DISPLAY ( char -- )

Writes the specified data byte char to the LCD display. Does not write to the Display Buffer. If an alphanumeric (character) display is being used, this command writes the specified ascii character at the current cursor position and increments the cursor position. (Caution: the cursor does not always follow a contiguous path as it is incremented; there may be discontinuities at the ends of lines.) Intermittently disables interrupts for 28 cycles (7 microseconds) per byte written to the display.

See also COMMAND>DISPLAY and UPDATE.DISPLAY
Pronunciation: "char-to-display"

CHARS/DISPLAY.LINE ( -- n )

Returns the number of characters per line in the LCD display as specified by the last execution of IS.DISPLAY. The default value of n after executing the "special cleanup mode" is 20, corresponding to the default 4-line by 20-character display. The result returned by this routine is used by BUFFER.POSITION, PUT.CURSOR, UPDATE.DISPLAY, and UPDATE.DISPLAY.LINE.
Pronunciation: "chars-per-display-line"

CHARS/LINE ( -- xaddr )

A user variable that contains the maximum number of characters that can be received by EXPECT. Also used by matrix print words M. M.. and M.PARTIAL to format their output. CHARS/LINE is initialized to a default value of 96 upon each COLD restart, and its value should not be increased above 96 unless the TIB is moved from its default location.
Pronunciation: "chars-per-line"
Attributes: U

CLEAR.BITS ( byte1\xaddr -- )

For each bit of byte1 that is set, clears the corresponding bit of the 8 bit value at xaddr. Disables interrupts for ten cycles (2.5 microseconds) to ensure an uninterrupted read/modify/write operation.

See also (CLEAR.BITS) and SET.BITS

CLEAR.BOOT.VECTOR ( -- )

Removes a boot vector from page 0x0C so that it will not be executed at reset or restart. Note that the page C write protect jumper must be re-moved for this function to be effective. This function is typically invoked interactively from the QED-Forth prompt. This function is called during a factory cleanup. but it is not called by NO.AUTOSTART.

See also Set_Boot_Vector

CLEAR.DISPLAY ( -- )

Clears (blanks) the LCD display, moves the cursor to home position (at the start of line 0). If a character display is in use (as specified by IS.DISPLAY), fills the 80 character DISPLAY.BUFFER with ascii blank characters. If a graphics display is being used in text mode, fills the buffer specified by GARRAY.XPFA with ascii blanks. If a graphics display is being used in graphics mode, erases (zeros) the buffer specified by GARRAY.XPFA. Intermittently disables interrupts for 28 cycles (7 microseconds) per byte written to the display.

See also INIT.DISPLAY

CLOCK.MONITOR.ID ( -- n )

Returns the interrupt identity code for the clock monitor interrupt. Used as an argument for ATTACH.
Pronunciation: "clock-monitor-i-d"

CMOVE ( xaddr1\xaddr2\u -- | xaddr1=src, xaddr2=dest, u = byte count )

If u is greater than 0, u consecutive bytes are copied from addresses starting at xaddr1 to addresses starting at xaddr2. The source and destination extended addresses may be located on different pages and the move may cross page boundaries. If the source and destination regions overlap and xaddr1 < xaddr2, CMOVE starts at high memory and moves toward low memory to avoid propagation of the moved contents. CMOVE always moves the contents in such a way as to avoid memory propagation. Speed is approximately 19 microseconds per byte.

See also CMOVE.MANY
Pronunciation: "c-move"

CMOVE.IN.PAGE ( addr1\addr2\u\page -- | addr1=src, addr2=dest, u = byte count )

If u is greater than 0, u consecutive bytes starting at addr1 are copied to the destination addresses starting at addr2 on the specified page. If the source and destination regions overlap and addr1 < addr2, CMOVE.IN.PAGE starts at high memory and moves toward low memory to avoid propagation of the moved contents. CMOVE.IN.PAGE always moves the contents in such a way as to avoid memory propagation. Speed is approximately 7.5 microseconds per byte.
Pronunciation: "c-move-in-page"

CMOVE.MANY ( xaddr1\xaddr2\d -- | xaddr1=src, xaddr2=dest, d = byte count )

If the 32-bit byte count d is greater than 0, d consecutive bytes are copied from addresses starting at xaddr1 to addresses starting at xaddr2. The source and destination extended addresses may be located on different pages and the move may cross page boundaries. If the source and destination regions overlap and xaddr1 < xaddr2, CMOVE.MANY starts at high memory and moves toward low memory to avoid propagation of the moved contents. CMOVE.MANY always moves the contents in such a way as to avoid memory propagation. Speed is approximately 19 microseconds per byte.
Pronunciation: "c-move-many"

CODE ( <name> -- )

Begins an assembly coded definition. Removes <name> from the input stream and creates a header for <name> that cannot be found in the dictionary until END.CODE executes. Executes ASSEMBLER so that the assembler mnemonics can be found by the interpreter. The assembly mnemonics between CODE and END.CODE form the body of the definition.

See also END.CODE, >ASSM, >FORTH
Attributes: D

COL->V ( col#\matrix.xpfa -- xvaddr\sep\d.#el )

Returns the vector representation xvaddr\sep\d.#el of the specified column in the specified matrix. xvaddr is the base address of the vector, sep is the element separation expressed as a multiple of 4 bytes (e.g., sep=1 means a vector of contiguous floating point numbers, sep=2 means elements are separated by 8 bytes, etc.) and the double number d.#el is the number of elements in the vector. In the case of a column in a matrix, sep=1 (i.e., column elements are stored in contiguous memory locations) and d.#el is the 32-bit equivalent of the number of rows in the matrix. Note that xvaddr must be 4-byte aligned (i.e., must be an even multiple of 4). The heap manager and array and matrix dimensioning words automatically perform the required 4-byte alignment.

See also ROW→ V
Pronunciation: "col-to-v"

COLD ( -- )

Disables interrupts and restarts the QED-Forth system and initializes all of the user variables to their default values. Initializes the following machine registers:

PORTG, DDRG, TMSK2, SPCR, BAUD, SCCR1, SCCR2, BPROT,
OPT2, OPTION, HPRIO, INIT, CSSTRH, CSCTL, CSGADR, CSGSIZ.

Initializes the vectors of the vital interrupts if INIT.VITAL.IRQS.ON.COLD has been executed. Calls ABORT which clears the stacks and calls either the QED-Forth interpreter or an autostart routine that has been installed using AUTOSTART. If COLD.ON.RESET has been executed, every reset or power-up will invoke a COLD (as opposed to a WARM) initialization sequence. Consult the Program Development Techniques chapter and the Interrupts, Initializations, and Autostarting chapter in the Software Manual for more information about cold restarts.

COLD.ON.RESET ( -- )

Initializes a flag in EEPROM that causes subsequent resets to execute a cold restart (as opposed to the standard warm-or-cold restart). This option is useful to help "bullet-proof" turnkeyed systems that have an autostart word installed; any error or reset causes a full COLD restart which initializes all user variables, after which the autostart routine completes the system initialization and enters the application routine. Implementation detail: Initializes location 0xAE1C in EEPROM to contain the pattern 13.

See also STANDARD.RESET

COLUMN.CONCATENATE ( matrix.xpfa1\matrix.xpfa2\matrix.xpfa3 -- )

Concatenates the two source matrices specified by matrix.xpfa1 and matrix.xpfa2 to form a destination matrix matrix.xpfa3 with more columns. The number of rows in the two source matrices must be the same. The destination may be one of the sources.

COLUMN.TRUNCATE ( matrix.xpfa1\matrix.xpfa2\n -- )

Copies all but the final n columns of the source matrix specified by matrix.xpfa1 to the destination specified by matrix.xpfa2. The destination may be the source.

COMMAND>DISPLAY ( byte -- )

Writes the specified byte to the LCD display as a command (as opposed to a character to be displayed). Does not modify the contents of the DISPLAY.BUFFER. Intermittently disables interrupts for 28 cycles (7 microseconds) per command byte written to the display.

See also CHAR>DISPLAY
Pronunciation: "command-to-display"

COMPILE ( <name> -- )

Removes the next <name> from the input stream. Use as:

: <namex>
   ... COMPILE <name> ...
;

where <namex> is typically immediate and <name> is typically not immediate. Compiles into the current definition code that will cause <name> to be compiled when <namex> is executed. That is, COMPILE defers the compilation of <name> until <namex> executes. Consult the Advanced Topics chapter of the Software Manual for further description and an example.

Attributes: C, I

COMPILE.CALL ( xcfa -- )

Compiles a call to the assembly language subroutine whose first byte of executable machine code is stored at xcfa. If no page change is needed at runtime, (COMPILE.CALL) is executed. If a page change is needed, an 8-byte sequence is compiled into the definitions area to accomplish the page change at run time.

COMPLEMENT ( w1 -- w2 )

Returns the ones complement of w1. That is, inverts each bit of w1 to produce w2.

CONSTANT ( w <name> -- )

Removes the next <name> from the input stream and defines a child word called <name> which when executed leaves the value w on the data stack. w is stored in the definitions area of the dictionary. <name> is referred to as a "constant". Use as:

w CONSTANT <name>

Attributes: D

CONTEXT ( -- xaddr )

A user variable that contains a 32-bit xhandle which in turn contains the xnfa of the top word in the vocabulary to be searched first. Thus CONTEXT X@ returns the xhandle of the search vocabulary, and CONTEXT X@ X@ returns the xnfa of the top word in the search vocabulary. In short, the contents of CONTEXT determine the search vocabulary.

See also FIND and CURRENT

Attributes: U

CONVERT ( ud1\xaddr1 -- ud2\xaddr2 )

Converts the numeric string starting at xaddr1+1 into the 32-bit number ud2. Conversion is accomplished by multiplying the double accumulator ud1 by the value in BASE and then adding the next digit from the string at xaddr1. Conversion ends when a non-convertible ASCII character is encountered in the string. Isolated embedded commas are ignored and are not treated as a non-convertible character. xaddr2 is the address of the first non-convertible character encountered in the string. For example, executing 0\0 " 123 " CONVERT leaves a 32-bit representation of the number 123 on the data stack under the xaddr of the terminating space in the string " 123 " .

COP.ID ( -- n )

Returns the interrupt identity code for the computer operating properly (COP) interrupt. Used as an argument for ATTACH.
Pronunciation: "cop-i-d"

COPY.ARRAY ( array.xpfa1\array.xpfa2 -- )

Dimensions the destination array specified by array.xpfa2 and copies the contents of the source array specified by array.xpfa1 into the destination. The source and destination can be in different heaps.

COPY.MATRIX ( matrix.xpfa1\matrix.xpfa2 -- )

Dimensions the destination matrix specified by matrix.xpfa2 and copies the contents of the source matrix specified by matrix.xpfa1 into the destination. The source and destination can be in different heaps.

COUNT ( x$addr -- xaddr\cnt | xaddr = x$addr+1 )

Unpacks the counted string whose count is stored at x$addr and whose first character is stored at x$addr+1. Returns the extended address of the first character under the count. The string may cross a page boundary.

COUNT.TYPE ( x$addr -- )

Unpacks count from x$addr on page and types the string. COUNT.TYPE is equivalent to COUNT TYPE

Attributes: M

CR ( -- )

Causes subsequent output to appear at the beginning of the next line by emitting a carriage return (ascii 13) followed by a line feed (ascii 10).
Pronunciation: "c-r"
Attributes: M

CR.BEFORE.MSG ( -- xaddr )

A user variable that contains a flag. If the flag is false (the default condition), system warnings and error messages are printed without first emitting carriage return/linefeed characters. This ensures smooth downloads if the host terminal is using the suggested technique of waiting for a linefeed character (ascii 10) before sending each new line of source code to the QED Board (see the Program Development Techniques chapter). If the CR.BEFORE.MSG flag is true, the error and warning messages are printed on a separate line, but the leading carriage return/linefeed that is emitted may cause the host terminal to send the next line of source code before the QED Board is capable of responding to it. Thus it is recommended that CR.BEFORE.MSG be kept in its default OFF state while downloading to the QED Board.
Pronunciation: "carriage-return-before-message"
Attributes: U

CREATE ( <name> -- )

Adds a new header for <name> to the names area. Executes BL WORD to parse the next space-delimited word <name> from the input stream. Converts the parsed string to upper case letters and searches the dictionary via (FIND) to check for uniqueness. A warning is issued if <name> is not unique.

Implementation detail: Creates a new header for <name> starting at the address pointed to by NP, links the header to the CURRENT vocabulary, and initializes the code field address in the header to the current value of DP. Updates the CURRENT vocabulary xhandle to point to the xnfa of <name> and updates NP to point to the byte after <name>'s header. The number of characters saved in the header is the lesser of the value in WIDTH or the actual number of characters in <name>, to a maximum of 31 characters. If locals are compiling, all characters are saved in the header to avoid non-uniqueness of local variables. An abort error occurs if the header cannot be stored (e.g., if NP does not point to RAM). If WIDTH is less than or equal to 1, CREATE resets WIDTH to 2.

Attributes: D

CREATE.RAMP ( start_speed\end_speed\accel\ticks_per_sec\start_ramp_addr\speeds_per_ramp -- steps_in_ramp | all parameters are integers )

Writes speed_per_ramp +1 entries into the RAMP.ARRAY starting at the specified start_ramp_addr to attain the specified starting and ending speeds and acceleration (or deceleration). Returns the number of steps in the created ramp. start_speed, end_speed and acceleration are all interpreted as positive numbers. Speeds are in units of steps per second if the motor is configured for full stepping, or halfsteps per second if the motor is configured for half stepping. The acceleration is in units of (half) steps per second per second. Speeds are clamped to the attainable range (between 0 and ticks_per_second), and the acceleration is clamped such that a maximum of 10 seconds is spent at any one transient speed in a ramp. Each ramp entry comprises a step_limit which specifies the number of steps to be taken at the speed, and a duty_cycle which specifies the speed (see the glossary entry for SPEED.TO.DUTY). If the specified speeds_per_ramp = 0, this function simply writes a "final" speed by setting the step_limit to 0. For non-zero speeds_per_ramp, this routine writes the specified number of ramp entries, plus an additional entry at the final speed with the step_limit set to 0 which tells the STEP.MANAGER that this is the final speed in the ramp. Note that higher level calling routines can write over the final speed, or concatenate two ramps to achieve a speed profile that ramps up to a steady speed for a specified number of steps, and then smoothly ramps down to a stopped state. Consult the high level source file steppers.4th in the Demos_and_Drivers directory of the distribution.

CURRENT ( -- xaddr )

A user variable that contains a 32-bit xhandle which in turn contains the xnfa of the top word in the vocabulary to which new definitions are added by CREATE. Thus CURRENT X@ returns the xhandle of the definitions vocabulary, and CURRENT X@ X@ is equivalent to LATEST, returning the xnfa of the latest word defined. In short, the contents of CURRENT determine the vocabulary to which new words are added.

See also CREATE and CONTEXT

Attributes: U

CURRENT.HEAP ( -- xaddr )

A user variable that holds the 32-bit extended address that specifies the end of the current heap. Executing CURRENT.HEAP X@ places the xaddress of the last+1 byte in the current heap on the data stack; the other heap control variables are stored just below this address in the heap.

See also IS.HEAP
Pronunciation: "current-heap"
Attributes: U

CUSTOM.ABORT ( -- xaddr )

A user variable that contains a flag. If the flag is TRUE, the abort routine whose xcfa is in UABORT is executed each time that ABORT is called. If the flag is FALSE, ABORT executes the default (ABORT) routine.

See also ABORT, (ABORT), and UABORT

Attributes: U

CUSTOM.ERROR ( -- xaddr )

A user variable that contains a flag. If the flag is TRUE, the error routine whose xcfa is in UERROR is executed in response to every system error. If CUSTOM.ERROR is FALSE, all system errors call the default (ERROR) routine.

See also (ERROR) and UERROR

Attributes: U

D+ ( d1\d2 -- d3 )

Adds two signed double numbers d1 and d2 giving the signed double number result d3.
Pronunciation: "d-plus"

D- ( d1\d2 -- d3 | d3 = d1 - d2 )

Subtracts two signed double numbers d1 and d2 giving the signed double number result d3.
Pronunciation: "d-minus"

D. ( wd -- )

Prints wd with no leading spaces and 1 trailing space. If the number base is decimal, wd is printed as a signed number in the range -2,147,483,648 to +2,147,483,647. In other bases wd is printed as an unsigned positive number.
Pronunciation: "d-dot"
Attributes: M, S

D.INSTANCE: ( u <name> -- | u is the size of the structure )

Removes <name> from the input stream and creates a structure instance called <name>, and allocates u bytes in the definitions area starting at HERE for the structure instance (the "D" in "D.INSTANCE:" refers to the Definitions area where the instance is allocated). Compare with V.INSTANCE:. When <name> is executed, the extended base address of the allocated structure instance is placed on the data stack. Typical use:

<structure.name> D.INSTANCE: <name>

where <structure.name> was defined using

STRUCTURE.BEGIN: <structure.name>
   ...
STRUCTURE.END

Executing <structure.name> leaves the structure size u on the stack, and D.INSTANCE: <name> allocates and names the instance. Executing

SIZE.OF <name>

places the allocated size of the instance on the stack. Note that the instance may cross page boundaries, and may increment the dictionary pointer DP so that it points to a new page.
Pronunciation: "d-instance"
Attributes: D

D.OVER.N ( d\n -- d\n\d )

Copies the double number located under the top data stack cell to the top of the data stack.
Pronunciation: "d-over-n"

D.R ( wd\+byte -- | +byte is field width )

Prints wd right-justified in a field of +byte characters. If +byte is less than or equal to the number of characters to be printed, the number is printed with no extra spaces. If the number base is decimal, wd is printed as a signed number in the range -2,147,483,648 to +2,147,483,647. In other bases w is printed as an unsigned positive number. To print wd as a positive unsigned number in decimal base, use UD.R
Pronunciation: "d-dot-r"
Attributes: M, S

D0<> ( wd -- flag )

Flag is TRUE if double number wd is not equal to zero, and FALSE otherwise.
Pronunciation: "d-zero-not-equal"

D0= ( wd -- flag )

Flag is TRUE if double number wd is equal to zero and FALSE otherwise.
Pronunciation: "d-zero-equal"

D2* ( d1 -- d2 | d2 = d1 * 2 )

Multiplies signed double number d1 by 2 giving d2. Overflow errors are not checked.
Pronunciation: "d-two-star"

D2/ ( d1 -- d2 | d2 = d1 / 2 )

Divides signed double number d1 by 2 giving d2.
Pronunciation: "d-two-slash"

D< ( d1\d2 -- flag )

Flag is TRUE if the signed double number d1 is less than the signed double number d2 and FALSE otherwise.
Pronunciation: "d-less-than"

D<> ( wd1\wd2 -- flag )

Flag is TRUE if the two double numbers are not equal and FALSE otherwise.
Pronunciation: "d-not-equal"

D= ( wd1\wd2 -- flag )

Flag is TRUE if the two double numbers are equal and FALSE otherwise.
Pronunciation: "d-equal"

D> ( d1\d2 -- flag )

Flag is TRUE if the signed double number d1 is greater than the signed double number d2 and FALSE otherwise.
Pronunciation: "d-greater-than"

D>R ( d -- )

Return Stack: ( R: – d )

Transfers the top double number on the data stack to the return stack.
Pronunciation: "d-to-r"
Attributes: C

D>S ( d -- n )

Converts the double number d to the single number n by dropping the most significant cell of d. There is an unchecked error if d cannot be represented by a 16-bit signed integer.
Pronunciation: "d-to-s"

D>S? ( d -- [d\2] or [n\1] )

If possible, converts double number d to a single number n and leaves n on the stack under a 1 flag. Otherwise leaves double number d on the stack under a 2 flag.
Pronunciation: "d-to-s-question"

DABS ( d1 -- +d2 )

Replaces double precision signed number d1 with its absolute value +d2. If d1 is positive, +d2 = d1. If d1 is negative, +d2 is the negative of d1.
Pronunciation: "d-abs"

DEALLOCATED ( xpfa -- )

De-allocates the heap memory associated with the data structure having the specified parameter field address xpfa. The xpfa is typically associated with a word defined by H.INSTANCE:. Typical use:

size.of.heap.item  H.INSTANCE:  <name>
SIZE.OF <name>   ' <name>  ALLOCATED
   ...
 ' <name>  DEALLOCATED

DEBUG ( -- xaddr )

A user variable that holds a flag. If true, this flag enables error checking by the word NEEDED and by some array and matrix routines. It also enables the trace printout of words that are compiled while TRACE is ON.

Attributes: U

DECIMAL ( -- )

Set the numeric conversion base to ten by storing decimal 10 into the user variable BASE.

DEFAULT.PAGE ( -- page | page = 0 )

Places a zero onto the data stack; this represents the default page assigned to the common memory (i.e., addresses above 0x8000).

DEFAULT.REGISTER.INITS ( -- )

Undoes the effect of the INSTALL.REGISTER.INITS command.

Implementation detail: sets the contents of location AE06H in EEPROM to 0xFF to ensure that default initializations will be used after subsequent resets. The default register initializations are:

Register   Register   Default
Name      Address   Value
OPTION   0x8039      0x33
TMSK2      0x8024      0x02
BPROT      0x8035      0x10
BAUD      0x802B      0x31

DEFAULT.TRACE.ACTION ( -- )

Installs NO.OP, a do-nothing word, as the trace action. Equivalent to

CFA.FOR  NO.OP  IS.TRACE.ACTION

See IS.TRACE.ACTION

DEFINITIONS ( -- )

Stores the contents of CONTEXT into CURRENT so that the search vocabulary is also the vocabulary to which new definitions are appended.

Attributes: I

DELETED ( array.xpfa -- | used for arrays and matrices )

De-allocates the heap space assigned to the specified array or matrix, and clears the parameter field to indicate that the data structure is no longer dimensioned. Use as:

' <name> DELETED

See DIMENSIONED, DIMMED

DEPTH ( -- +n | +n = stack depth )

+n is the number of cells on the data stack before +n was placed on the stack.

DFIXX ( r -- d )

d is the 32 bit integer closest to the floating point number r.

See also FIXX
Pronunciation: "d-fix"
Attributes: S

DFLOT ( d -- r )

Converts the double number d to the nearest floating point number r. Note that there is a potential loss of resolution in this conversion, since d is represented by 32 significant bits, while r has a 16-bit mantissa.

See also FLOT
Pronunciation: "d-f-lot"
Attributes: S

DIGIT ( char -- [ n\-1 ] or [ 0 ] )

Converts ascii char to binary digit n in the current number base and leaves n on the stack under a true flag. If char cannot be converted to a valid digit, returns a false flag.

DIM.CONSTANT.ARRAY: ( u1\...\uN\N\n <name> -- | N=#dim, n=bytes/element )

Removes <name> from the input stream and creates and dimensions an array in the definitions area. This is useful for building lookup tables that will reside in flash memory after the application is finished and write-protected. u1, u2, …uN specify the number of elements in each dimension, N specifies the number of dimensions, and n specifies the number of bytes per element. <name> behaves exactly as an array does; its stack picture is

( indices -- xaddr )

and an element xaddress is also returned upon execution of the command

indices  ' <name> []

DIM.CONSTANT.ARRAY: creates a header for <name> in the names area of the dictionary. It creates and initializes a parameter field and a "handle" (to mimic a heap handle) in the definitions area, and allots the required number of bytes for the array in the definitions area. ABORTs if #dim is invalid (<1 or >MAX#DIMENSIONS). The array may cross page boundaries, and may increment the dictionary pointer DP so that it points to a new page.

Example of use:

To define and dimension a constant array to have 2 dimensions (3 rows and 4 columns) with 6 bytes per element, execute:

3 4 2 6 DIM.CONSTANT.ARRAY: <name>

Restrictions: In general, constant arrays should be dimensioned only once at the time of creation; redimensioning to a larger size could write over other routines in the dictionary and cause a crash.
Pronunciation: "dim-constant-array"
Attributes: D

DIM.CONSTANT.MATRIX: ( #rows\#cols <name> -- )

Removes <name> from the input stream and creates and dimensions a matrix in the definitions area. This is useful for building lookup tables that will reside in flash memory after the application is finished and write-protected. <name> behaves exactly as a matrix does; its stack picture is:

( row#\col# -- xaddr )

and an element xaddress is also returned upon execution of the command

 row# col#  ' <name> M[]

DIM.CONSTANT.MATRIX: creates a header for <name> in the names area of the dictionary. It creates and initializes a parameter field and a "handle" (to mimic a heap handle) in the definitions area, and allots the required number of bytes for the matrix in the definitions area. The matrix is assigned #rows rows and #cols columns, 2 dimensions, and 4 bytes/element. The matrix may cross page boundaries, and may increment the dictionary pointer DP so that it points to a new page.

Example of use:

To define and dimension a constant matrix to have 3 rows and 4 columns, execute:

3 4 DIM.CONSTANT.MATRIX: <name>

Restrictions: Care must be used when using matrix operators that assume that the matrix resides in the current heap. In general, constant matrices should be dimensioned only once at the time of creation; redimensioning to a larger size could write over other routines in the dictionary and cause a crash.
Pronunciation: "dim-constant-matrix"
Attributes: D

DIMENSIONED ( u1\...\uN\N\n\array.xpfa -- )

Dimensions the array specified by array.xpfa. u1…uN specify the number of elements in each dimension, N specifies the number of dimensions, and n specifies the number of bytes per element. DIMENSIONED executes DELETED to de-allocate any heap space previously allocated to the array, and then writes the dimensioning information into the array's parameter field and allocates the required number of bytes in the heap. ABORTs if there is not enough heap space or if N is invalid (N must be between 1 and MAX#DIMENSIONS, inclusive).

Example of use:

To define and dimension an array to have 2 dimensions (3 rows and 4 columns) with 6 bytes per element, execute:

ARRAY:   <name>
3 4 2 6   ' <name>  DIMENSIONED

DIMMED ( #rows\#cols\matrix.xpfa -- )

Dimensions the matrix specified by matrix.xpfa to have #rows rows and #cols columns. The number of dimensions is 2, and there are 4 bytes per element (i.e., the size of a floating point number). DIMMED executes DELETED to de-allocate any heap space previously allocated to the matrix, and then writes the dimensioning information into the parameter field and allocates the required number of bytes in the heap. ABORTs if there is not enough heap space, or (if DEBUG is ON) if the number of rows or columns is greater than 16,383. For example, to define and dimension a matrix to have 3 rows and 4 columns, execute:

MATRIX: <name>
3 4 ' <name>  DIMMED

DIN ( -- wd )

Compile Time: ( <name> – )

DIN removes the next word from the input stream, converts it to a 32-bit double number wd in the current number base (or in hexadecimal if the number is preceeded by 0x or 0X), and executes 2LITERAL which leaves the number on the stack if QED-Forth is in execution mode, or compiles it as a literal in the current definition if QED-Forth is in compilation mode. If DIN is not used, 32-bit numbers in the input stream are truncated to 16 bits. An error is issued if <name> cannot be converted to a valid number. Typical use:

HEX DIN 12345678   ( -- 5678 \ 1234 )
D.      12345678 ok

Pronunciation: "d-in"

DINT ( r -- d )

d is the double number representation of the integer part of floating point number r.

See also INT.PART
Pronunciation: "d-int"

DINT.FLOOR ( r -- d )

d is the greatest double number less than or equal to r.

See also INT.FLOOR
Pronunciation: "d-int-floor"

DISABLE.INTERRUPTS ( -- )

Sets the interrupt mask bit (the "I bit") in the condition code register to globally disable interrupts.

DISABLE.SERIAL2 ( -- )

Disables the secondary serial port (serial2) which is supported by QED-Forth's software UART. Implementation detail: Locally disables the serial2 output interrupt OC4 and disconnects the pin control logic associated with the PA4 output. Locally disables the serial2 input interrupt IC4/OC5. Clears the resource variable SERIAL2.RESOURCE to 0\0.
Pronunciation: "disable-serial-two"

DISK.RESOURCE ( -- xresource )

A resource variable associated with the mass memory block buffers. After initialization to 0\0, should be accessed only by the words GET ?GET and RELEASE. Initialized to 0\0 by the system startup software.

See also RESOURCE.VARIABLE:

DISPLAY.BUFFER ( -- xaddr )

Returns the extended base address of the buffer that holds the display data. UPDATE.DISPLAY.LINE and UPDATE.DISPLAY write the contents of this buffer to the LCD display. If a character display is in use, xaddr is the base address of an 80 character buffer in the system RAM. If a graphics display is in use, xaddr is the starting address of the array associated with GARRAY.XPFA. Each byte in this buffer represents a character position or graphical byte on the LCD display. To display characters on the LCD display, simply write the desired ascii characters or graphical data into this buffer and execute UPDATE.DISPLAY.LINE or UPDATE.DISPLAY. UPDATE.DISPLAY.LINE causes the contents of a specified line in DISPLAY.BUFFER to be written to the corresponding line of the display. UPDATE.DISPLAY causes the contents of all lines in DISPLAY.BUFFER to be written to the corresponding lines of the display.

See also $>DISPLAY and BUFFER.POSITION

DISPLAY.HEAP ( -- xaddr )

Returns the extended address that points to the top of the heap containing the graphics array. The default display heap is located at 3000 to 0x45FF on page 0x0F. Caution: adding items to the DISPLAY.HEAP is not recommended; if there is not enough room for the GARRAY, INIT.DISPLAY will not dimension it. However, if you must dimension additional heap items in this heap, execute the following commands:

CURRENT.HEAP X@ \ save the prior heap specifier on dstack

DISPLAY.HEAP CURRENT.HEAP X! \ display.heap is the heap

< dimension or delete heap items here>

CURRENT.HEAP X! \ restore prior heap specifier

DISPLAY.OPTIONS ( flag1\flag2\flag3\flag4 -- )

Sets the display and cursor options on the LCD display. The meanings of the input flags are as follows:

flag1 = display.enabled?
flag2 = cursor.on?
flag3 = cursor.blinking?
flag4 = text.mode?

If flag1 is true, the contents of the display are visible; if false, the display appears blank. If flag2 is true, the cursor is on (typically an underscore character); if false, the cursor is off. If flag3 is true, the cursor blinks (typically a flashing box the size of a single character); if false, the cursor blink is turned off. If flag4 is true, the display is operating in "text mode"; if false, it is operating in "graphics mode". (If a Toshiba graphics display is in use, flag4 can take on the additional value 1, meaning that both text and graphics modes are enabled. In this case, you must set different home locations for the text and graphics regions.) Note that graphics mode should only be specified if a graphics display is in use. Note also that the cursor is never visible in graphics mode. INIT.DISPLAY (which is executed upon each reset or restart) leaves the display enabled with the cursor off and cursor blink off and the "home" location in the upper left corner at display ram address 0. Implementation detail: In addition to writing the appropriate command byte to the display, DISPLAY.OPTIONS stores the command byte in a headerless system variable called *PRIOR.CURSOR.STATE. This variable is referenced by UPDATE.DISPLAY.LINE and UPDATE.DISPLAY to blank the cursor during updates to character displays (to prevent annoying flickering) and restore it to its prior state after the update is complete. It is also used by LINES/DISPLAY to infer whether the display is being operated in text mode or graphics mode, which in turn determines whether LINES/DISPLAY reports the number of character lines or the number of pixel lines in the display. This routine intermittently disables interrupts for 28 cycles (7 microseconds) per command byte written to the display.

See also IS.DISPLAY

DMAX ( d1\d2 -- [d1] or [d2] | retains the greater of d1 and d2 )

Retains the greater of two signed double numbers and drops the other.
Pronunciation: "d-max"

DMIN ( d1\d2 -- [d1] or [d2] | retains the lesser of d1 and d2 )

Retains the lesser of the two signed double numbers and drops the other.
Pronunciation: "d-min"

DNEGATE ( d1 -- d2 | d2 = two's complement of d1 )

Negates signed double number d1 to yield d2. The negative (two's complement) is computed by inverting all of the bits in d1 and adding a 32-bit 1 to the result.
Pronunciation: "d-negate"

DO ( w1\w2 -- | w1 = limit, w2 = starting index )

Return Stack: ( R: – w1\w2 )

Used inside a colon definition to mark the beginning of a counted loop structure that is terminated by LOOP or +LOOP. DO sets up the loop control parameters (index and limit) on the return stack with w1 as the limit and w2 as the starting index. Because the loop parameters are maintained on the return stack, caution must be exercised when using the operators >R and R> inside a loop. DO…LOOPs may be nested as long as each DO is matched with a corresponding LOOP or +LOOP in the same definition as DO. w1 and w2 may either be a pair of signed integers or a pair of unsigned integers.

DO may only be used within a definition. Use as:

w1 w2 DO ... LOOP

or

w1 w2 DO ...  n +LOOP

The loop terminates when index crosses the boundary between limit-1 and limit in either direction. An error is issued if DO is not properly paired with LOOP or +LOOP inside a definition.

Before the first iteration, DO tests to see if index = limit (that is, w2 = w1); if so the loop is skipped and control is immediately passed to the word after LOOP or +LOOP. For all iterations the test for termination is done by LOOP or +LOOP at the end of the DO…LOOP or DO…+LOOP control structure. This behavior is taken from the ANSI X3.215-1994 definition of ?DO; that is, our DO behaves identically to the ANSI FORTH ?DO. The ANSI standard DO always caused the loop to execute at least once; our DO and the ANSI ?DO do not.

See also LOOP  +LOOP  I  J  K  I'  LEAVE

Attributes: C, I

DOES> ( -- )

Used in a high level defining word to mark the beginning of the specification of the run-time action of the child words. Use as:

: <namex>
   <DBUILDS   compile time action
   DOES>  run time action
;

or as

: <namex>
   <VBUILDS   compile time action
   DOES>  run time action
;

where <namex> is referred to as a "defining word". Executing the statement

<namex> <child's.name>

defines the child word. The code after <DBUILDS or <VBUILDS specifies the action to be taken while defining the child word, and the code after DOES> specifies the action to be taken when the child word executes.

The default run-time action of DOES> is to leave the extended parameter field address of the child word on the data stack. Thus, the code between DOES> and ; should expect the xpfa on the stack when the child executes. Consult the definitions of <DBUILDS and <VBUILDS for examples of use.
Pronunciation: "does"

DOT.PRODUCT ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- r )

Returns the dot product r of the vectors specified by xvaddr1\sep1\d.#el and xvaddr2\sep2\d.#el. The dot product is calculated by multiplying the corresponding elements of the two vectors and summing the result into a floating point accumulator. The two vector specifications may refer to the same vector.

Attributes: S

DOUBLE-> ( u1 <name> -- u2 )

Adds a named member to the structure being defined and reserves room for a double number field in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u2 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "double"
Attributes: D

DOUBLE: ( <name> -- )

Defines a 32-bit self-fetching variable. Removes <name> from the input stream and creates a child word (a self-fetching variable) called <name> and allots 4 bytes in the variable area as the parameter field where the self-fetching variable's value is stored. When <name> is executed it leaves its value (a 32-bit number) on the stack. Thus <name> behaves like a 2constant when executed. Unlike a 2constant, its parameter field is in the variable area and so can always be modified. The TO command is used to store a value into the self-fetching variable. In general, code using self-fetching variables runs faster than does similar code that uses standard variables because the fetch and store operations are integrated into the action of the variable. Use as:

DOUBLE: <name>

Pronunciation: "double-colon"
Attributes: D

DOUBLES-> ( u1\u2 <name> -- u3 )

Adds a named member to the structure being defined and reserves room for u2 double numbers in the structure. Removes <name> from the input stream and creates a structure field called <name>. u1 is the structure offset initialized by STRUCTURE.BEGIN:. u3 is the updated offset to be used by the next member defining word or by STRUCTURE.END. When <name> is later executed, it adds its offset u1 to the extended address found on the data stack which is typically the start xaddress of an instance of the data structure; the result is the xaddress of the desired member in the structure.
Pronunciation: "doubles"
Attributes: D

DOWNLOAD.MAP ( -- )

Sets a flag in EEPROM and changes the state of a latch in the onboard PALs to put the download memory map into effect on flash-equipped QED-Flash Boards. After execution of this routine, and upon each subsequent reset or restart, pages 4, 5, and 6 are addressed in RAM, and pages 1, 2, and 3 are addressed in flash memory. This allows code (and Forth names) to be compiled into RAM on pages 4, 5 and 6 and then transferred to flash using the PAGE.TO.FLASH function. To establish the standard memory map, consult the glossary entry for STANDARD.MAP. Note that the standard map is active after a "factory cleanup" operation.

DP ( -- xaddr )

User variable that contains the 32-bit definitions pointer. The contents of DP are placed on the stack by HERE and are modified by ALLOT. The command DP X@ is equivalent to HERE; it yields the xaddr of the next available dictionary location. The command DP @ is equivalent to DPAGE; it yields the page of the definitions area.
Pronunciation: "d-p"
Attributes: U

DPAGE ( -- page )

Returns the page of the definitions area of the dictionary. Equivalent to DP @
Pronunciation: "d-page"
Attributes: U

DPICK ( d\wn-1\...w1\w0\+n -- d\wn-1\...\w1\w0\d | 0 <= +n <= 255 )

Copies the double number whose most significant cell is the nth item on the stack (0-based, not including n) to the top of the stack. An unchecked error occurs if there are fewer than +n+2 cells on the data stack. 0 DPICK is equivalent to 2DUP, 1 DPICK is equivalent to D.OVER.N, 2 DPICK is equivalent to 2OVER.
Pronunciation: "d-pick"

DR> ( -- d )

Return Stack: ( R: d – )

Transfers the top double number on the return stack to the data stack.
Pronunciation: "d-r-from"
Attributes: C

DR>DROP ( -- )

Return Stack: ( R: d – )

Removes the top double number on the return stack.
Pronunciation: "d-r-from-drop"
Attributes: C

DR@ ( -- d )

Return Stack: ( R: d – d )

Copies the top double number on the return stack to the data stack.
Pronunciation: "d-r-fetch"
Attributes: C

DRANGE ( d1\d2\d3 -- d1\flag )

Flag is TRUE if d1 is greater than or equal to d2 and less than or equal to d3. Otherwise flag is FALSE.
Pronunciation: "d-range"

DROP ( w -- )

Drops the top cell from the stack.

DSCALE ( d1\n -- d2 )

Arithmetically (i.e., preserving sign) shifts double number d1 by n bit places to yield signed double number result d2. If n is positive, d1 is shifted left; if n is negative, d1 is shifted right. The absolute value of n determines the number of bits of shifting. For example, 1 DSCALE is equivalent to D2* and -1 DSCALE is equivalent to D2/ . There is an unchecked error if the absolute value of n is greater than 31.
Pronunciation: "d-scale"

DU< ( ud1\ud2 -- flag )

Flag is TRUE if the unsigned double number ud1 is less than the unsigned double number ud2.
Pronunciation: "d-u-less-than"

DU> ( ud1\ud2 -- flag )

Flag is TRUE if the unsigned double number ud1 is greater than the unsigned double number d2.
Pronunciation: "d-u-greater-than"

DUMP ( xaddr\u -- | xaddr = start address, u = number of bytes )

Displays the contents of u bytes starting at the specified xaddr. The contents are dumped as hexadecimal bytes regardless of the current number base, and the ascii equivalent contents are also displayed. For example, to display 0x40 bytes starting at address 0x1000\1, execute:

HEX  1000  1  40  DUMP

and to display the last 0x10 bytes on page 1 and the first 0x20 bytes on page 2,

Type: 7FF0 1 30 DUMP

DUMP calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

See also PAUSE.ON.KEY

Attributes: M, S

DUMP.INTEL ( xaddr1\addr2\u -- )

xaddr1 is the location of the first byte to be dumped, addr2 specifies the starting address reported in the dump, and u is the number of bytes to be dumped. Dumps the contents of u bytes starting at xaddr using the standard ascii Intel hex format which is useful for transferring data between devices. The line format is:

:{#bytes}{reported.addr}{00}{byte}{byte} ...{byte}{checksum}

All numbers are in hexadecimal base. Each line starts with a : character, followed by a 2-digit number of bytes (20, indicating that the contents of 0x20 bytes are displayed per line), followed by a 4-digit starting address for the line, followed by 00, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum followed by a carriage return/linefeed. The checksum is calculated by summing each of the bytes on the line into an 8-bit accumulator and negating (two's complementing) the result. The hex dump ends with the line

:00000001FF

For example, to dump 0x40 bytes starting at QED Board address 0x1000\1 so that the bytes reside at the beginning of a target memory device, execute:

HEX  1000  01  0000   40  DUMP.INTEL

which specifies 0x1000\1 as the starting address, 0000 as the reported base address in the memory device, and 0x40 as the number of bytes to be dumped. To dump the last 0x20 bytes on page 1 and the first 0x40 bytes on page 2 so that they reside at locations 0x7FE0 through 0x803F in the target memory device, execute

7FE0  1  7FE0   60    DUMP.INTEL

The complementary word RECEIVE.HEX loads QED memory starting at any location based on a received Intel or Motorola hex file. DUMP.INTEL calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

See also DUMP.S1, DUMP.S2, RECEIVE.HEX and PAUSE.ON.KEY

Attributes: M, S

DUMP.REGISTERS ( -- xaddr )

A user variable that holds a flag. If the flag is true, a definition that has been compiled with TRACE ON prints the contents of the registers before each instruction during a trace. If the flag is false, the register contents are not printed during a trace.

DUMP.S1 ( xaddr1\addr2\u -- )

xaddr1 is the location of the first byte to be dumped, addr2 specifies the starting address reported in the dump, and u is the number of bytes to be dumped. Dumps the contents of u bytes starting at xaddr using the standard ascii Motorola S1 hex format which is useful for transferring data between devices. Motorola S1 records report 16 bit addresses. (To report full 24 bit addresses, use DUMP.S2.) Outputs an S0 header record which is

S00900004845414445524D

then as many S1 data records as required, followed by an S9 termination record which is

S9030000FC

The Motorola S1 hex line format is:

S1{#bytes}{16bit.reported.addr}{byte}...{byte}{chksum}

All numbers are in hexadecimal base. Each line starts with a the record type (S1 in this case), followed by a 2-digit number of bytes (23, which equals 0x20 bytes per line plus 3 bytes for the reported address and checksum), followed by a 4-digit starting address for the line, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum. The checksum is calculated by summing each of the bytes on the line (excluding the record type) into an 8-bit accumulator and (one's) complementing the result.

For example, to dump 0x40 bytes starting at QED Board address 0x1000\1 so that the bytes reside at the beginning of a target memory device, execute:

HEX  1000  01   0000   40   DUMP.S1

which specifies 0x1000\1 as the starting address, 0000 as the reported base address in the memory device, and 0x40 as the number of bytes to be dumped. To dump the last 0x20 bytes on page 1 and the first 0x40 bytes on page 2 so that they reside at locations 0x7FE0 through 0x803F in the target memory device, execute:

7FE0  1   7FE0    60     DUMP.S1

The complementary word RECEIVE.HEX loads QED memory starting at any location based on a received Motorola or Intel hex file. DUMP.S1 calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

See also DUMP.S2, DUMP.INTEL, RECEIVE.HEX and PAUSE.ON.KEY

Attributes: M, S

DUMP.S2 ( xaddr1\d\u -- )

xaddr1 is the location of the first byte to be dumped, double number d specifies the 24 bit starting address reported in the dump, and u is the number of bytes to be dumped. Dumps the contents of u bytes starting at xaddr1 using the standard ascii Motorola S2 hex format which is useful for burning flash memory chips and transferring data between devices. Motorola S2 records report 24 bit addresses which are useful in capturing and transferring complete application programs to/from flash memory. (To report 16 bit addresses, use DUMP.S1.) Dumps an S0 header record which is

S00900004845414445524D

then as many S2 data records as required, followed by an S9 termination record which is

S9030000FC

The Motorola S2 hex line format is:

S2{#bytes}{24bit.reported.addr}{byte}...{byte}{chksum}

All numbers are in hexadecimal base. Each line starts with a the record type (S2 in this case), followed by a 2-digit number of bytes (24, which equals 0x20 byte per line plus 4 bytes for the reported address and checksum), followed by a 6-digit starting address for the line, followed by the contents of the memory locations (2 hex digits per byte), and concluding with a checksum. The checksum is calculated by summing each of the bytes on the line (excluding the record type) into an 8-bit accumulator and (one's) complementing the result. DUMP.S2 calls the word PAUSE.ON.KEY, so the dump responds to XON/XOFF handshaking and can be aborted by typing a carriage return.

See also DUMP.S1, DUMP.INTEL, RECEIVE.HEX and PAUSE.ON.KEY

Example of use: Assume that you have created an application program in pages 4, 5, and 6, and used PRIORITY.AUTOSTART to configure a flash-based autostart vector so that the application runs automatically upon each power-up and restart. To dump a complete application program that resides on pages 4, 5 and 6, so that the bytes reside at the beginning of a flash memory device, execute:

HEX
0000 04   DIN  000000    8000  DUMP.S2
0000 05   DIN  008000    8000  DUMP.S2
0000 06   DIN  010000    8000  DUMP.S2

Now you can edit the resulting file, concatenate the 3 dumps into 1 large S-record by removing all but the first and last S0 (header) and S9 (termination) records, and re-save the file. To transfer the application to a new QED board, simply execute

DOWNLOAD.MAP
0 4 RECEIVE.HEX   <send the captured file>
4 PAGE.TO.FLASH
5 PAGE.TO.FLASH
6 PAGE.TO.FLASH
STANDARD.MAP

This is a time-effective method of mass producing QED-based products running a turnkeyed autostart program.

Attributes: M, S

DUP ( w -- w\w )

Duplicates the top cell of the data stack.
Pronunciation: "dupe"

DUP.HEAP.ITEM ( xhandle1 -- [xhandle2] or [0\0] )

Given the 32-bit handle xhandle1 of a source heap item, creates a duplicate heap item with identical contents in the same heap and returns its handle xhandle2. Returns 0\0 if xhandle1 is not a valid handle or if there is insufficient memory in the heap. To copy a heap item into a different heap, use TRANSFER.HEAP.ITEM.
Pronunciation: "dupe-heap-item"

DUP>R ( w -- w )

Return Stack: ( R: – w )

Copies the top cell on the data stack to the return stack.
Pronunciation: "dupe-to-r"
Attributes: C