# 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:

Page Starting character
This page  ! " # $% & ' ( ) * + , - . / 0 1 2 3 4 8 : ; < = > ? @ A B C D  Page E-O  E F G H I J K L M N O  Page P-Z-}  P Q R S T U V W X Y Z [ \ ] ^ _  | } ~ Listed functions are alphabetized in the following ASCII order. Forth words are not case sensitive. You can click on the following characters to be taken directly to the glossary entries starting with that character. ##### ! ! ( 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 #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 #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 #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 #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 #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 #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

$>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

$>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 $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 $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)

(#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)) ( [...]\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!)

(+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!)

(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@)

(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)

(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)

(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)

(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:)

(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!)

(C!) ( byte\addr -- )

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

##### (C@)

(C@) ( addr -- byte )

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

##### (CHANGE.BITS)

(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)

(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)

(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)

(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"

##### DISPLAY.HEAP

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

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?
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

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

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

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

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.

Examples of DO…LOOP and DO…+LOOP
Code Output
4 4 DO I . LOOP (no execution)
4 0 DO I . LOOP 0 1 2 3
4 5 DO I . LOOP 5 6 7 8 … -2 -1 0 1 2 3
4 0 DO I . 1 +LOOP 0 1 2 3
4 0 DO I . 2 +LOOP 0 2
0 4 DO I . -1 +LOOP 4 3 2 1 0
0 4 DO I . -2 +LOOP 4 2 0

See also LOOP  +LOOP  I  J  K  I'  LEAVE

Attributes: C, I

##### DOES>

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

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->

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:

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->

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

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

DPAGE ( -- page )

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

##### DPICK

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>

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

DR>DROP ( -- )

Return Stack: ( R: d – )

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

##### DR@

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

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

DROP ( w -- )

Drops the top cell from the stack.

##### DSCALE

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<

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>

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

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

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

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

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

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

DUP ( w -- w\w )

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

##### DUP.HEAP.ITEM

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

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

This page is about: Forth Firmware Library Glossary Words A-D, ANSI Forth Language – A glossary of the functions in the V4.4 Forth firmware library for the controllers based on the 68HC11 microcontrollers. QED-Forth is both a programming language and a real-time embedded operating system. Words starting with the characters: ! " # \$ ' ( * + , - . / 0 1 2 3 4 8 : ; < = > ? @ A B C or D. Embedded real time operating system RTOS, Forth firmware programs, embedded Forth language, Forth compiler, Forth interpreter, interpretive computer languages