# Forth V4.0/V4.2 Function Glossary

This document provides a glossary of the Forth firmware library available in V4.0/V4.2 Forth for the QED Board. QED-Forth is both a programming language and a real-time embedded operating system.

Software development in Forth uses the Mosaic IDE Integrated Development Environment; this is the same IDE used for software development in C. While Forth programmers will not use the IDE's C compiler, the IDE provides a full-featured text editor and customized terminal for rapid Forth code downloads and interactive Forth debugging sessions with the 68HC11 processor on the controller board.

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

The following glossary entries are alphabetized in ASCII Order:
 !"#$%&'()*+,-./0123456789:;⇔?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_{|}~  ##### ! ! ( 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 00x7FFF 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.

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

##### (>DAC)

(>DAC) ( byte\n -- | byte = data, n = channel# )

Writes the specified data byte to the digital to analog converter (DAC) channel specified by n. Note that the eight valid DAC channel numbers are 1 ≤ n ≤ 8. The data transfer uses the SPI (serial peripheral interface); use INIT.A/D12&DAC to initialize the SPI interface. To maximize speed, this routine does not GET or RELEASE the SPI.RESOURCE. Consequently, this routine should not be used in a multitasking environment where another task might require access to the SPI. Executes in about 40 microseconds with a 16 MHz processor crystal.

Pronunciation: "paren-to-dac"

##### (@)

(@) ( 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/D12.MULTIPLE)

(A/D12.MULTIPLE) ( xaddr\u1\u2\flag\n -- | u1=timing,u2=#samples,flag=mode,n= channel# )

Acquires u2 samples from the 12 bit analog to digital (A/D) converter and stores the samples as sequential 16 bit values starting at the specified xaddr. u1 is a timing parameter, flag specifies the conversion mode, and n specifies the channel number of the A/D (0 < = n < = 7). The meaning of the flag is as follows:

   Flag value   Type of conversion
-1      single ended, unipolar
0      differential, unipolar
1      single ended, bipolar
2      differential, bipolar

Single-ended sampling means that the input voltage of the specified channel is referenced to VRL which is typically analog ground. Differential sampling means that the voltage input of the specified channel's "partner" is subtracted from the voltage of the specified channel and the resulting voltage is digitized by the A/D. The pairing of "partner" channels is as follows: [0,1], [2,3], [4,5], and [6,7]. Unipolar sampling means that the input is a positive voltage that swings from VRL to VRH (typically 0 to +5 V), while bipolar sampling means that the input is interpreted as a signed 12 bit representation of an input that swings from -VRH to +VRH (typically -5V to +5V). Note that conversion of inputs more negative than -4.0 V may require an external -5V supply connected to pin 39 of the Analog I/O connector. The data transfer uses the SPI (serial peripheral interface); use INIT.A/D12&DAC to initialize the SPI interface. To maximize speed, this routine does not GET or RELEASE the SPI.RESOURCE. Consequently, this routine should not be used in a multitasking environment where another task might require access to the SPI; see A/D12.MULTIPLE. If the specified xaddr is in common memory, the first sample is taken after 58 microseconds and subsequent samples are taken every (27.5+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 68 microseconds and subsequent samples are taken every (50+2.5*u1) microseconds. Of course, the operation of interrupts (including timesliced multitasking) will affect these sampling times.

Pronunciation: "paren-A-to-D-twelve-multiple"

##### (A/D12.SAMPLE)

(A/D12.SAMPLE) ( flag\n -- u | flag=conversion mode, n=channel#, u=result )

Acquires and places on the stack a single sample u from the 12 bit analog to digital (A/D) converter. n specifies the channel number of the A/D (0 < = n < = 7). The meaning of the flag is as follows:

   Flag value   Type of conversion
-1      single ended, unipolar
0      differential, unipolar
1      single ended, bipolar
2      differential, bipolar

Single-ended sampling means that the input voltage of the specified channel is referenced to VRL which is typically analog ground. Differential sampling means that the voltage input of the specified channel's "partner" is subtracted from the voltage of the specified channel and the resulting voltage is digitized by the A/D. The pairing of "partner" channels is as follows: [0,1], [2,3], [4,5], and [6,7]. Unipolar sampling means that the input is a positive voltage that swings from VRL to VRH (typically 0 to +5 V), while bipolar sampling means that the input is interpreted as a signed 12 bit representation of an input that swings from -VRH to +VRH (typically -5V to +5V). Note that conversion of inputs more negative than -4.0 V may require an external -5V supply connected to pin 39 of the Analog I/O connector. The data transfer uses the SPI (serial peripheral interface); use INIT.A/D12&DAC to initialize the SPI interface. To maximize speed, this routine does not GET or RELEASE the SPI.RESOURCE. Consequently, this routine should not be used in a multitasking environment where another task might require access to the SPI; see A/D12.SAMPLE. Executes in 88 microseconds.

Pronunciation: "paren-A-to-D-twelve-sample"

##### (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.

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.

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; see IS.DISPLAY. 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.

##### 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  I'  J  K  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.

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 the S2 RAM, and pages 1, 2, and 3 are addressed in the S1 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, see 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 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.

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, see 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.

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, see 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.

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

##### ELSE

ELSE ( -- )

Used in a colon definition to mark the beginning of the "else portion" of an IF … ELSE … ENDIF conditional structure (ENDIF and THEN are synonyms). Use as:

flag IF   words to execute if flag is true
ELSE       words to execute if flag is false
ENDIF

If the flag passed to IF is true, when ELSE is encountered control is passed to the word following ENDIF. If the flag passed to IF is FALSE, control is immediately passed to the word following ELSE.

Attributes: C, I

##### EMIT

EMIT ( char -- )

Displays char by sending it via the serial I/O port. EMIT is a vectored routine that executes the routine whose xcfa is installed in the user variable UEMIT. The default installed routine called is EMIT1 which sends the character via the primary serial port (supported by the 68HC11's hardware UART). EMIT2 may be installed in UEMIT by USE.SERIAL2 or SERIAL2.AT.STARTUP; EMIT2 sends the character via the secondary serial port (supported by QED Forth's software UART and using pins PA3 and PA4).

Attributes: M, U

##### EMIT1

EMIT1 ( char -- )

Displays a character by sending it via the primary serial port (serial1) associated with the 68HC11's on-chip hardware UART. Before sending the character, EMIT1 waits (if necessary) for the previous character to be sent, and executes PAUSE while waiting. The most significant byte of the input data stack cell is ignored. EMIT1 is the default EMIT routine installed in the UEMIT 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, EMIT1 does not GET or RELEASE the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, EMIT1 GETs and RELEASEs the SERIAL1.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, EMIT1 GETs but does not RELEASE the SERIAL1.RESOURCE.

Pronunciation: "emit-one"
Attributes: M

##### EMIT2

EMIT2 ( char -- )

Writes the specified ascii character to the output buffer of the secondary serial port (serial2) for subsequent transmission. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). If the serial2 transmitter is idle (and if the serial2 port and its interrupts have been properly initialized) then the character is transmitted immediately. Otherwise the character will be transmitted after the prior characters in the output buffer are transmitted. If the 80 character output buffer is full when EMIT2 is executed, EMIT2 PAUSEs and waits until room becomes available in the buffer (as a result of a character being sent out). The most significant byte of the input data stack cell is ignored. EMIT2 can be made the default EMIT routine installed in the UEMIT user variable after each reset or restart by executing SERIAL2.AT.STARTUP. If the value in SERIAL.ACCESS is RELEASE.AFTER.LINE, EMIT2 does not GET or RELEASE the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.ALWAYS, EMIT2 GETs and RELEASEs the SERIAL2.RESOURCE. If SERIAL.ACCESS contains RELEASE.NEVER, EMIT2 GETs but does not RELEASE the SERIAL2.RESOURCE.

Pronunciation: "emit-two"
Attributes: M

##### ENABLE.INTERRUPTS

ENABLE.INTERRUPTS ( -- )

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

##### END-CODE

END-CODE ( sys -- | balances CODE )

A synonym for END.CODE

Pronunciation: "end-code"

##### END.CODE

END.CODE ( sys -- | balances CODE )

Terminates an assembly code definition which started with CODE. Executes SMUDGE so that the header created by CODE can be found in the dictionary. Checks to make sure that no extra items were left on the stack during the definition process. Stores the contents of CURRENT into CONTEXT so that ASSEMBLER is no longer the search vocabulary.

Pronunciation: "end-code"

##### ENDCASE

ENDCASE ( n -- )

Used inside a colon definition to mark the end 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 doesn't equal n2 or n3 or n4
ENDCASE

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

Pronunciation: "end-case"
Attributes: C, I

##### ENDIF

ENDIF ( -- )

Synonym for THEN. Used inside a colon definition to mark the end of an

  IF ... ELSE ... ENDIF

or IF … ENDIF

conditional structure. The word following ENDIF is executed after the IF or ELSE (if present) part of the conditional executes. An error is issued if ENDIF is not paired with IF or ELSE in a colon definition.

Pronunciation: "end-if"
Attributes: C, I

##### ENDIFTRUE

ENDIFTRUE ( -- )

Marks the end of a conditional structure that is used outside a colon definition. Use as:

flag  IFTRUE .... OTHERWISE ....  ENDIFTRUE

or

flag  IFTRUE ....  ENDIFTRUE

The execution mode conditional structure can be used to conditionally compile portions of source code. Note that IFTRUE/OTHERWISE/ENDIFTRUE statements can not be nested.

Pronunciation: "end-if-true"

##### ENDOF

ENDOF ( -- )

Used inside a CASE … ENDCASE structure to mark the end of a conditional statement that starts with OF or RANGE.OF or URANGE.OF. If the OF portion of the case statement is true, ENDOF branches to the word after ENDCASE. An error is issued if OF and ENDOF are not properly paired.

Pronunciation: "end-of"
Attributes: C, I

##### ERASE

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

Stores a zero byte in each of u consecutive bytes beginning at xaddr. The specified region may cross page boundaries. Does nothing if u = 0.

##### EVALUATE

EVALUATE ( x$addr -- ) Interprets the counted string located at x$addr. Use as:

" <words to be executed>" EVALUATE

The string need not end with a space. EVALUATE provides one method of compiling a reference to a word that has not yet been defined. For example,

: EARLY.WORD
...
" INITIALIZE.EVERYTHING" EVALUATE
...
;

Even though the routine INITIALIZE.EVERYTHING has not yet been defined, EARLY.WORD will call it if INITIALIZE.EVERYTHING has been defined by the time EARLY.WORD is finally executed at runtime. Note that EVALUATE must search the dictionary at runtime to be able to execute INITIALIZE.EVERYTHING. For a more efficient means of implementing forward references, see REDEFINE.

Implementation detail: EVALUATE saves the contents of the input stream variables UTIB, #TIB, >IN, and BLK, then sets these variables to reference the specified x$addr, then calls INTERPRET, and finally restores the original values to the input stream variables. ##### EXECUTE EXECUTE ( xcfa -- ) Executes (calls) the routine whose executable machine instructions begin at the specified code field xaddress. The xcfa can be on any page. ##### EXIT EXIT ( -- ) Specifies a termination point in a definition. EXIT is an immediate word that compiles code that, when later executed, clears the locals off the return stack (if present), and pops the top value off the return stack and returns control to the calling word. When compiled into a definition, EXIT causes the word to terminate at that point when the word is later executed. An unchecked (and usually severe) error occurs if the return stack does not hold a valid return address (for example, if EXIT is used between >R and R> or inside a DO…LOOP or FOR…NEXT loop). To exit a definition from inside a single DO…LOOP, execute UNLOOP (which removes and drops 2 items from the rstack) to discard the loop index and limit from the return stack before calling EXIT. One UNLOOP is needed for each nested DO… LOOP. To exit a definition from inside a FOR…NEXT loop, call R>DROP to discard the loop index before calling EXIT. One R>DROP is needed for each nested FOR…NEXT. Attributes: C, I ##### EXPECT EXPECT ( xaddr\+n -- ) Receives a string of characters from the serial port and stores them in a buffer in memory starting at xaddr. Terminates when +n characters have been received or a carriage return occurs, whichever occurs first. Characters are echoed via the serial port. The carriage return is neither saved in the buffer nor echoed. Tab characters are echoed; however, they are saved in the buffer as TAB.WIDTH spaces. The backspace or delete character (ascii 8 or 127) removes the most recently received character from the buffer unless there are no characters in the buffer. Null characters (ascii 0) and linefeeds (ascii 10) are ignored. XON and XOFF characters are ignored except that they cause the XMIT.DISABLE flag in the user area to be set if XOFF is received or cleared if XON is received. Character case is not altered. The user variable SPAN is set equal to the number of characters received (but not including the terminating carriage return, if present). EXPECT is called by QUERY to accept serial input to the TIB. Attributes: M ##### F! F! ( r\xaddr -- ) Stores a floating point number at xaddr. A synonym for 2!. Pronunciation: "f-store" ##### F* F* ( r1\r2 -- r3 ) Multiplies floating point number r1 by r2 giving r3. Pronunciation: "f-star" Attributes: S ##### F** F** ( r1\r2 -- r3 ) r3 equals r1 raised to the r2 power; i.e., r3 = r1^r2. Overflows if r1 is negative. Pronunciation: "f-star-star" Attributes: S ##### F*/COUNTER F*/COUNTER ( -- xaddr ) A user variable that holds a 16 bit counter that is incremented with each call to F* or F/. Used by the BENCHMARK: and (BENCHMARK:) routines. Pronunciation: "f-star-slash-counter" Attributes: U ##### F+ F+ ( r1\r2 -- r3 ) Adds floating point number r2 to r1 giving the sum r3. Pronunciation: "f-plus" Attributes: S ##### F+COUNTER F+COUNTER ( -- xaddr ) A user variable that holds a 16 bit counter that is incremented with each call to F+ or F-. Used by the BENCHMARK: and (BENCHMARK:) routines. Pronunciation: "f-plus-counter" Attributes: U ##### F- F- ( r1\r2 -- r3 ) Subtracts floating point number r2 from r1 giving the difference r3. Pronunciation: "f-minus" Attributes: S ##### F. F. ( r -- ) Displays r using the default format as specified by the most recent execution of FIXED FLOATING or SCIENTIFIC. FLOATING is the default format after executing FP.DEFAULTS or after a cold restart. See also F>FIXED$, F>SCIENTIFIC$, and F>FLOATING$

Pronunciation: "f-dot"
Attributes: M, S

##### F.OVER.N

F.OVER.N ( r\w -- r\w\r )

Copies the floating point value r located under the top data stack cell to the top of the data stack.

Pronunciation: "f-over-n"

##### F/

F/ ( r1\r2 -- r3 )

Divides floating point number r1 by r2 giving the result r3.

Pronunciation: "f-slash"
Attributes: S

##### F0<

F0< ( r -- flag )

Flag is TRUE if floating point number r is less than zero, FALSE otherwise.

Pronunciation: "f-zero-less-than"

##### F0<=

F0<= ( r -- flag )

Flag is TRUE if floating point number r is less than or equal to 0, FALSE otherwise.

Pronunciation: "f-zero-less-than-or-equal"

##### F0<>

F0<> ( r -- flag )

Flag is TRUE if the floating point number is not equal to zero, and FALSE otherwise.

Pronunciation: "f-zero-not-equal"

##### F0=

F0= ( r -- flag )

Flag is TRUE if the floating point number equals zero and FALSE otherwise.

Pronunciation: "f-zero-equal"

##### F0>

F0> ( r -- flag )

If floating point number r is greater than zero, flag equals TRUE; otherwise, flag equals FALSE.

Pronunciation: "f-zero-greater-than"

##### F0>=

F0>= ( r -- flag )

Flag is TRUE if floating point number r is greater than or equal to 0, FALSE otherwise.

Pronunciation: "f-zero-greater-than-or-equal"

##### F2*

F2* ( r1 -- r2 )

Floating point number r2 equals r1 * 2.

Pronunciation: "f-two-star"
Attributes: S

##### F2/

F2/ ( r1 -- r2 )

Floating point number r2 equals r1 divided by 2.

Pronunciation: "f-two-slash"
Attributes: S

##### F2DROP

F2DROP ( r1\r2 -- )

Drops two floating point numbers (4 cells) from the data stack.

Pronunciation: "f-two-drop"

##### F2DUP

F2DUP ( r1\r2 -- r1\r2\r1\r2 )

Duplicates the top two floating point numbers on the data stack.

Pronunciation: "f-two-dupe"

##### F<

F< ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is less than r2, FALSE otherwise.

Pronunciation: "f-less-than"

##### F<=

F<= ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is less than or equal to r2.

Pronunciation: "f-less-than-or-equal"

##### F<>

F<> ( r1\r2 -- flag )

Flag is TRUE if the two floating point numbers are not equal and FALSE otherwise.

Pronunciation: "f-not-equal"

##### F=

F= ( r1\r2 -- flag )

Flag is TRUE if the two floating point numbers are equal and FALSE otherwise.

Pronunciation: "f-equal"

##### F>

F> ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is greater than r2, FALSE otherwise.

Pronunciation: "f-greater-than"

##### F>=

F>= ( r1\r2 -- flag )

Flag is TRUE if floating point number r1 is greater than or equal to r2.

Pronunciation: "f-greater-than-or-equal"

##### F>FIXED$F>FIXED$ ( r -- x$addr\flag ) Converts r to a counted ascii string starting at x$addr in FIXED format. If the conversion is successful, flag is TRUE. If r cannot be represented as an ascii string in FIXED format (i.e., if the values of LEFT.PLACES and RIGHT.PLACES are inappropriate) then xaddr contains the string "won'tfit" and flag is false. The FIXED format is composed of (an optional) sign, LEFT.PLACES digits, a decimal point, RIGHT.PLACES digits, and a trailing space: -xxx.yyy If the NO.SPACES flag is false (the default condition), the field size equals LEFT.PLACES + RIGHT.PLACES + 3 and numbers are decimal aligned. The size of the string is clamped to a maximum of 32 characters. Setting TRAILING.ZEROS true displays all trailing zeros to the right of the decimal point to a maximum of RIGHT.PLACES. Pronunciation: "f-to-fixed-string" Attributes: S ##### F>FLOATING

F>FLOATING$( r -- x$addr\true )

Converts r to an ascii string at x$addr using FLOATING format which selects FIXED format unless the number can be displayed with greater resolution using scientific notation, in which case SCIENTIFIC format is used (see F>FIXED$ and F>SCIENTIFIC). If FILL.FIELD if OFF (the default condition), the string is displayed using the minimum possible field size, and numbers are not decimal aligned. If FILL.FIELD is ON, the field size of the string is always equal to the scientific field size, which is MANTISSA.PLACES+8, and numbers are decimal aligned for neat display of tabular data. The string includes a trailing space unless NO.SPACES is true. The flag on top of the stack is always true because any valid floating point number can be represented in the FLOATING format. Pronunciation: "f-to-floating-string" Attributes: S ##### F>R F>R ( r -- ) Return Stack: ( R: – r ) Transfers the top floating point number on the data stack to the return stack. Pronunciation: "f-to-r" Attributes: C ##### F>SCIENTIFIC

F>SCIENTIFIC$( r -- x$addr\true )

Attributes: U

##### FILL.MANY

FILL.MANY ( xaddr\d\b -- | d = byte count, b = fill value )

The specified byte b is stored in each of d consecutive addresses beginning at xaddr. The specified region may cross page boundaries. Does nothing if d = 0.

##### FIND

FIND ( <name> -- [ xcfa\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, FIND leaves a 0 on the stack. If the word is found, FIND 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. 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. Find also invokes a COLD restart if POCKET is not in common memory.

##### FINT

FINT ( r1 -- r2 )

If the absolute value of r1 is less than 2^31, r2 is the floating point representation of the integer part (truncated toward zero) of r1. For these numbers, FINT is the equivalent of DINT DFLOT. If the absolute value of r1 exceeds 2^31, FINT returns r2 = r1 and sets the OVERFLOW flag.

Pronunciation: "f-int"

##### FIRST

FIRST ( -- xaddr )

Returns the extended address of the lower boundary of the block buffers; that is, the address of the first byte of the first block buffer. Equivalent to UFIRST X@ . Initialized by BLOCK.BUFFERS.

Attributes: U

##### FIXED

FIXED ( -- )

Sets the default printing format used by F. to fixed. Numbers are decimal aligned, and RIGHT.PLACES and LEFT.PLACES determine the field width.

See also F>FIXED$##### FIXED. FIXED. ( r -- ) Prints r using FIXED format. Does not change the default printing format. See also F>FIXED$

Pronunciation: "fixed-dot"
Attributes: M, S

##### FIXX

FIXX ( r -- n )

Rounds r to the nearest integer n. OVERFLOW is set if needed.

Attributes: S

##### FLN

FLN ( r1 -- r2 )

r2 is the natural logarithm of r1.

Pronunciation: "f-l-n"
Attributes: S

##### FLOATING

FLOATING ( -- )

Sets the default printing format used by F. to floating. The floating format uses FIXED format if the number can be represented with the same or more significant digits as it would if it were represented in SCIENTIFIC format. Otherwise, it uses SCIENTIFIC format.

See also F>FLOATING$##### FLOATING. FLOATING. ( r -- ) Prints r using FLOATING format. See also F>FLOATING$

Pronunciation: "floating-dot"
Attributes: M, S

##### FLOG10

FLOG10 ( r1 -- r2 )

r2 is the base 10 logarithm of r1.

Pronunciation: "f-log-ten"
Attributes: S

##### FLOG2

FLOG2 ( r1 -- r2 )

r2 is the base 2 logarithm of r1.

Pronunciation: "f-log-two"
Attributes: S

##### FLOOR

FLOOR ( r1 -- r2 )

r2 is the floating point representation of the greatest integer less than or equal to r1.

Attributes: S

##### FLOT

FLOT ( n -- r )

Converts the 16 bit integer n to its floating point representation r.

Pronunciation: "float"
Attributes: S

##### FMAX

FMAX ( r1\r2 -- [r1] or [r2] )

Retains the greater of r1 and r2.

Pronunciation: "f-max"

##### FMIN

FMIN ( r1\r2 -- [r1] or [r2] )

Retains the lesser of r1 and r2.

Pronunciation: "f-min"

##### FNEGATE

FNEGATE ( r1 -- r2 )

r2 is the negative of r1.

Pronunciation: "f-negate"

##### FNUMBER

FNUMBER ( x$addr -- [r\-1] or [0] ) Attempts to convert the space-delimited counted ascii string at x$addr into a valid floating point number r. Returns r under a true flag if the conversion is successful; otherwise returns a false flag. x$addr is the address of the text string's count byte. The string at x$addr must end with a blank; the blank may or may not be included in the count. Strings parsed by the commands BL WORD obey this rule.

Pronunciation: "f-number"
Attributes: S

##### FOR

FOR ( u1 -- )

Return Stack: ( R: – u1 )

Used inside a colon definition to mark the beginning of a count-down loop structure that is terminated by NEXT. Sets up loop index u1 on the return stack. Use as:

u1     FOR  <words to be executed u1+1 times>
NEXT

0 FOR…NEXT executes 1 time, 1 FOR…NEXT executes 2 times, 65,535 FOR…NEXT executes 65,536 times, etc. Because the loop index is maintained on the return stack, caution must be exercised when using the operators >R and R> inside a loop. FOR…NEXT loops may be nested as long as each FOR is matched with a corresponding NEXT in the same definition as FOR; otherwise, an error is issued. FOR … NEXT loops execute faster than DO … LOOP constructs. The word I may be used inside a FOR NEXT loop. J K I' and LEAVE may not be used in a FOR NEXT loop.

Attributes: C, I

##### FORGET

FORGET ( <name> -- )

Removes <name> from the input stream and searches for it in the CURRENT vocabulary. If <name> is found, deletes it from the dictionary and removes all words defined after <name> by adjusting DP, NP, and the xhandle of the CURRENT vocabulary. An error occurs if <name> is not found. FORGET does not de-allocate space in the variable area (VP is not adjusted). Use of ANEW for dictionary cleanup avoids this problem. Likewise, heap space is not de-allocated by FORGET; use of ON.FORGET solves this problem. When a word is about to be forgotten, FORGET checks to see if its name is ON.FORGET. Words with the name ON.FORGET are executed before being forgotten. This allows cleanup of heap items or other cleanup actions. A warning is issued if execution of FORGET leaves any of the pointers DP, NP, or VP pointing to non-RAM locations. Use this word with caution; it is possible to FORGET the entire operating system!

##### FORTH

FORTH ( -- )

Specifies FORTH as the vocabulary to be searched first during dictionary searches. Implementation detail: stores the 32-bit xhandle of the FORTH vocabulary into the user variable CONTEXT.

##### FOVER

FOVER ( r1\r2 -- r1\r2\r1 )

Places a copy of r1 on top of the data stack.

Pronunciation: "f-over"

##### FP&STRING.POP

FP&STRING.POP ( -- )

Return Stack: ( R: 15 cells – )

Pops off the return stack the values of the scratchpad user variables placed there by FP&STRING.PUSH and restores the popped values to the user area. Also restores PAD to the value it had before FP&STRING.PUSH executed. FP&STRING.PUSH and FP&STRING.POP are intended to be used in interrupt service routines that call floating point operations and/or floating point string conversion and/or integer string conversion operations. Execution time is approximately 113 microseconds.

Pronunciation: "f-p-and-string-pop"
Attributes: S

##### FP&STRING.PUSH

FP&STRING.PUSH ( xaddr -- | xaddr is temporary PAD )

Return Stack: ( R: – 15 cells )

Example of use: Assume that a foreground program is performing a matrix inversion and printing the results. This involves floating point additions and multiplications as well as number-to-string conversion. The following simple interrupt service routine would function correctly:

   FVARIABLE    LATEST.DATA
<another xaddr in ram>   XCONSTANT   STRING.DESTINATION
: INTERRUPT.SERVICE   ( -- )
LATEST.DATA F@ 2.0 F*

Attributes: U

##### LIMIT

LIMIT ( -- xaddr )

Returns the extended address of the upper boundary+1 of the block buffers; that is, the address one greater than the last byte in the last buffer. Initialized by BLOCK.BUFFERS. Equivalent to ULIMIT X@

Pronunciation: "paren-limit"
Attributes: U

##### LINES/DISPLAY

LINES/DISPLAY ( -- n )

Returns the number of lines in the LCD display. For character displays and for graphics displays being operated in "text mode", the result n equals the number of character lines (rows) in the display (the allowed values are 2, 4, 8 or 16 lines per display). For graphics displays being operated in "graphics mode", the result n equals the number of horizontal pixels on the display (which in turn is 8 times the number of character lines on the display). The type of display and the display mode (text mode vs. graphics mode) are determined by the most recent execution of DISPLAY.OPTIONS or INIT.DISPLAY (which implements the configuration specified by IS.DISPLAY). The default value of n after executing the "special cleanup mode" is 4, 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: "lines-per-display"

LINK ( xnfa1\xnfa2 -- )

Sets the link field in the name of the word referenced by name field address xnfa2 to point to the name referenced by xnfa1. In other words, it changes the way that backward-linked name list or vocabulary is searched so that the name associated with xnfa1 is encountered just after the name associated with xnfa2 (see FIND). LINK can be used in several interesting ways. For example, if xnfa1 = xnfa2, LINK designates the associated name as the bottom name in a linked list, effectively "sealing" the linked name list or vocabulary. For example, to define a new sealed vocabulary, execute

VOCABULARY NEW.VOCAB
NEW.VOCAB DEFINITIONS   FORTH
\ new definitions now go into NEW.VOCAB,
\ but FORTH words can be accessed in the definitions
: #1.WORD   ....   ;
: #2.WORD   ....   ;
\ define as many words as needed in NEW.VOCAB
NFA.FOR  #1.WORD  XDUP  LINK   \ seal the vocabulary

Make sure that xnfa2 is in modifiable RAM memory when LINK is executed. Alternatively, instead of sealing the vocabulary by making #1.WORD the bottom name, we could execute

NFA.FOR  FORTH    NFA.FOR  #1.WORD    LINK

to link #1.WORD to FORTH which is the very first (bottom) name in the QED-Forth name list. This has the advantage of keeping the vocabulary's contents small while allowing FORTH to be recognized from within the new vocabulary. This allows graceful exit to the main FORTH vocabulary after executing NEW.VOCAB DEFINITIONS.

LINK_FILE_IO ( -- )

This function (present in kernel versions starting with V4.05) links in the Forth headers of the Memory Interface Board’s ATA Flash Card Software Package into the linked list of Forth names.

See the MIB/ATA Flash Card Users Manual for information on how to use this function. Because the Memory Interface Board has been obsoleted by the Compact Flash Wildcard and its associated kernel extension software, this function is typically not used.

##### LITERAL

LITERAL ( -- w )

Compile Time: ( w – )

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

: <name>    ( -- n )
[ CHARS/LINE @ ] LITERAL
;

This compiles as a literal the value of CHARS/LINE that exists when the definition is compiled. When <name> is later executed, this value will be placed on the stack.

Attributes: I

##### LN(2)

LN(2) ( -- r )

Places the floating point representation of the natural logarithm of 2 (0.69314) on the stack.

Pronunciation: "l-n-of-two"

LOAD.MATRIX ( xpfa <text> -- | expects numbers in input stream )

Repeatedly calls NEXT.NUMBER to get as many numbers as needed to fill the matrix specified by xpfa. The first row is filled first (starting at the left, i.e., at the first column), then the next row, etc. Carriage returns and tabs can be used to format the numbers if desired. The numbers can be valid integers or floating point numbers; NEXT.WORD automatically converts the integers to their floating point equivalents using FLOT. Non-numeric text in the input is ignored until the matrix is filled, but be careful: any valid number encountered by LOAD.MATRIX will be converted and placed in the matrix, even if it is within parentheses or after a comment delimiter such as \. Integers are converted according to the current number base. Use as

MATRIX: MAT.A 2 3 ' MAT.A DIMMED \ def & dimension

' MAT.A LOAD.MATRIX 99 3 4.2 5.3 8 3 \ init matrix

Attributes: M, S

##### LOCALS{

LOCALS{ ( [...] -- | items are removed to initialize the local variables )

Return Stack: ( R: – […] | stack frame is placed on return stack,removed by ; )

Used within a colon definition to begin a command sequence that defines from 1 to 16 local variables. The syntax of the simplest type of local statement is:

LOCALS{ <name.1> <name.2>... <name.n> }

The names between LOCALS{ and the terminating } are given temporary headers that remain effective for the duration of the current definition. If the first 2 characters in the name of a local are d& or D& (suggesting a 32-bit double number value) or f& or F& (suggesting a 32-bit floating point value) or x& or X& (suggesting a 32-bit extended address) then the local is defined as a 32-bit quantity. All other local variables are defined as 16-bit quantities. At runtime (when the definition containing the LOCALS{ command is executed) the code compiled by LOCALS{ initializes the values of each of the named local variables to a corresponding item on the data stack. The top item is removed from the data stack and loaded into <name.1>, the next item on the data stack is removed and loaded into <name.2>, etc. A single cell is removed from the stack for each 16-bit local, and two cells are removed from the stack for each 32-bit local. Each local variable behaves just like a self-fetching variable. When executed, the local leaves its value on the stack. Its value can be initialized or modified by placing the desired value on the stack and invoking the TO operator followed by the name of the local variable.

An alternative syntax for the locals declaration is:

LOCALS{ <name.1> <name.2> ... | <name.a> <name.b> ... }

where the locals defined between LOCALS{ and the | (bar) are initialized to the values on the data stack as explained above, and the locals defined between the | and the terminating } are left uninitialized. If certain local variables are to be initialized by a TO statement later in the definition, it is better to define them as uninitialized locals to save execution time. If none of the locals need to be initialized, the syntax:

LOCALS{  | <name.a> <name.b> ... }

is acceptable. Locals can be used in recursive definitions; each execution of the word allocates a new frame on the return stack where the values of the locals are kept.

Usage rules: The locals command sequence,

LOCALS{ ... | ... }

may occupy multiple lines in the source code; however, no comments may appear between LOCALS{ and }. If using a disk block for input, the command must reside in a single block. To avoid problems with non-uniquely named local variables the convention of using names beginning with & is recommended. Only one

LOCALS{ ... | ... }

command sequence is allowed per definition and within the declaration only one | is allowed. The LOCALS{ declaration must not be inside a conditional structure such as an IF … ELSE … ENDIF structure. The number of local variables defined must be greater than 0 and less than or equal to 16. The local variable names defined in the body of a word are forgotten after the definition is finished. Colon definitions using locals should not call CREATE or other defining words and should not manipulate CURRENT. Locals cannot be used between <DBUILDS or <VBUILDS and DOES> in a defining word. Locals should not be used in interrupt service routines or in code called by interrupt service routines.

Pronunciation: "locals-start"
Attributes: C, D, I

##### LOG10(2)

LOG10(2) ( -- r )

Pushes the base-10 logarithm of 2 onto the data stack.

Pronunciation: "log-ten-of-two"

##### LOG2

LOG2 ( u -- n )

n is the integer part of the base 2 logarithm of u.

Pronunciation: "log-two"

##### LOOP

LOOP ( -- )

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

LOOP increments the loop index on the return stack by one. If the index then equals the loop limit, 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 (w1 - w2 - 1) times
LOOP

An error is issued if DO and LOOP are not paired within a definition.

See also LOOP  +LOOP  I  I'  J  K  LEAVE

Attributes: C, I

Attributes: C, I

##### LU.BACKSUBSTITUTION

LU.BACKSUBSTITUTION ( residue.matrix.xpfa\matrix.xpfa\index.array.xpfa -- )

Used in conjunction with LU.DECOMPOSITION to solve a set of simultaneous equations. This solution method is very efficient when solving a system of equations with multiple right hand sides (i.e., multiple residues). residue.matrix.xpfa specifies a column matrix containing the right hand side of the system of equations, matrix.xpfa specifies a matrix containing the LU decomposition of the coefficient matrix, and index.array.xpfa specifies an array that was dimensioned and initialized by LU.DECOMPOSITION. LU.BACKSUBSTITUTION replaces residue.matrix.xpfa with the solution of the equation (i.e., with the values of the unknown quantities). For application information and an example, see LU.DECOMPOSITION.

Pronunciation: "l-u-back-substitution"
Attributes: S

##### LU.DECOMPOSITION

LU.DECOMPOSITION ( index.array.xpfa\matrix.xpfa -- n | n = determinant's.sign )

Finds the LU ("lower/upper") decomposition of the source matrix specified by matrix.xpfa and stores the decomposed matrix back into the source matrix. Also calculates the sign n of the determinant of the source matrix which can be passed to ?DETERMINANT to find the determinant of the source matrix. Dimensions and initializes the array associated with index.array.xpfa to contain values that are then used by LU.BACKSUBSTITUTION.

Application: Sometimes it is necessary to solve several systems of equations, each having the same left hand sides but with different right hand sides, or residue matrices. The system of equations is represented by the matrix equation

AX=B

where X is a column matrix of unknowns, A is a matrix of coefficients, and B is a column matrix known as the "residue matrix" that represents the right hand side of the equations. A second set of equations with a different residue matrix could be represented as

AX' = C

where C is the residue matrix and X' is the matrix of unknowns that solves the equation. These sets of equations are most efficiently solved by finding the LU decomposition of A using the word LU.Decomposition. "LU" refers to "lower/upper", a decomposition method that minimizes the propagation of round-off error. Now the matrix equations can be expressed as

LU(A) X= B
LU(A) X'= C

where LU(A) is the decomposition of the A matrix. These equations can be solved for the unknown matrix X with a minimum of computation using the word LU.BACKSUBSTITUTION. To solve a given equation for several residue matrices, LU(A) needs only to be computed once. LU.BACKSUBSTITUTION can then solve each residue matrix to get each solution matrix with minimal additional work.

Example of use:

ARRAY: INDEX.ARRAY \ define this temporary array

MATRIX: A <initialize A here> \ define & init coefficients

MATRIX: B <initialize B here> \ define & init residue #1

MATRIX: C <initialize C here> \ define & init residue #2

' INDEX.ARRAY ' A LU.DECOMPOSITION

      \ replace A with its LU decomposition

DROP \ drop the determinant sign

' B ' A ' INDEX.ARRAY LU.BACKSUBSTITUTION

   \ for residue matrix B, find the unknowns X
\ and place them in B

CR ." The answer to AX = B is " ' B M. \ print solution

' C ' A ' INDEX.ARRAY LU.BACKSUBSTITUTION

      \ for residue matrix C, find the
\ unknowns X' and place them in C

CR ." The answer to AX' = C is " ' C M. \ print solution

Pronunciation: "l-u-decomposition"
Attributes: S

##### M*

M* ( n1\n2 -- d )

Multiply signed single precision integers n1 and n2 producing signed double precision product d.

Pronunciation: "m-star"

##### M*MT

M*MT ( matrix.xpfa1\matrix.xpfa2 -- )

Multiplies the source matrix.xpfa1 by its transpose to form the specified destination matrix.xpfa2. The name of the routine suggests the order of the operands.

Pronunciation: "m-star-m-transpose"
Attributes: S

##### M.

M. ( matrix.xpfa -- )

Prints the contents of the matrix specified by matrix.xpfa using the default printing format (FIXED, FLOATING, or SCIENTIFIC). The print is performed with FILL.FIELD ON so that tabular format (constant field width, decimal alignment) is maintained. Printed elements are delimited with spaces and with carriage returns and continuance marks (…). Output line length is limited to 6 characters less than the contents of the user variable CHARS/LINE. M. calls the word PAUSE.ON.KEY, so the print responds to XON/XOFF handshaking and can be aborted by typing a carriage return; see PAUSE.ON.KEY.

Pronunciation: "m-dot"
Attributes: M, S

##### M..

M.. ( matrix.xpfa -- )

Prints the name of the matrix specified by matrix.xpfa followed by a display of its contents as performed by M.

Pronunciation: "m-dot-dot"
Attributes: M, S

##### M.PARTIAL

M.PARTIAL ( low.row#\high.row#\low.col#\high.col#\matrix.xpfa -- )

Prints a portion of the matrix specified by low.row# through high.row#, inclusive and low.col# through high.col#, inclusive, using the default print format (FIXED, FLOATING, or SCIENTIFIC). The print is performed with FILL.FIELD ON so that tabular format (constant field width, decimal alignment) is maintained. Printed elements are delimited with spaces and with carriage returns and continuance marks (…). Output line length is limited to 6 characters less than the contents of the user variable CHARS/LINE.

Typical use: Assume that MAT.A is dimensioned to have 8 rows and 9 columns. The following command prints the last 5 elements in each of the first 3 rows:

0 2  4 8  ' MAT.A   M.PARTIAL

M.PARTIAL calls the word PAUSE.ON.KEY, so the print responds to XON/XOFF handshaking and can be aborted by typing a carriage return; see PAUSE.ON.KEY.

Pronunciation: "m-dot-partial"
Attributes: M, S

##### M/MOD

M/MOD ( d1\n1 -- n2\d2 | n2 = remainder, d2 = quotient )

Divides double number d1 by integer n1 giving integer remainder n2 and double number quotient d2. Uses signed math. Division by zero (n1 = 0) yields n2 = 0XFFFF and d2 = FFFF0XFFFF.

Pronunciation: "m-slash-mod"

##### MAILBOX:

MAILBOX: ( <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 reserved cells that hold the mailbox's contents. <name> is referred to as a "mailbox". Use as:

MAILBOX: <name>

Mailboxes are used in multitasked systems to share information between tasks and to synchronize tasks to one another. If the mailbox's contents equal 0\0, the mailbox is empty; it contains a message if its contents are non-zero. Before its first use, the mailbox must be initialized to 0\0. After initialization to 0\0, the only operators that should access the mailbox are SEND ?SEND RECEIVE and ?RECEIVE. Consult the multitasking chapter for applications information and examples.

Attributes: D

##### MANTISSA.PLACES

MANTISSA.PLACES ( -- xaddr )

A user variable that holds the number of digits to be displayed in the mantissa when a floating point number is displayed in SCIENTIFIC format.

Attributes: U

##### NO.VITAL.IRQ.INIT

NO.VITAL.IRQ.INIT ( -- )

Writes a pattern into EEPROM so that subsequent cold restarts will not initialize the COP, clock monitor, illegal opcode, and OC2 interrupt vectors. This option is provided for programmers interested in installing their own interrupt service routines in any of these four vectors. Can be undone by INIT.VITAL.IRQS.ON.COLD. Implementation detail: Initializes location 0xAE1B in EEPROM to contain the pattern 0x13.

Pronunciation: "no-vital-i-r-q-init"

##### NOT

NOT ( w -- flag )

flag is the boolean inverse of w. That is, if w = 0, the flag is TRUE. If w is non-zero, the flag is FALSE.

##### NP

NP ( -- xaddr )

User variable that contains the 32-bit pointer to the names area of the dictionary. The contents of NP are placed on the stack by NHERE and are modified by NALLOT. The command NP X@ is equivalent to NHERE; it yields the xaddr of the next available location in the names area. The command NP @ is equivalent to NPAGE; it yields the page of the names area.

Pronunciation: "n-p"
Attributes: U

##### NPAGE

NPAGE ( -- page )

Returns the page of the names area in the dictionary. Equivalent to NP @

Pronunciation: "n-page"
Attributes: U

Attributes: U

##### ROLL

ROLL ( wn\wn-1\...\w0\+n -- wn-1\...\w0\wn | 0 ≤ +n ≤ 255 )

Transfers the +nth item (not including +n) on the data stack to the top of the data stack. The top stack item is item#0, the next is item#1, etc. 0 ROLL does nothing, 1 ROLL is equivalent to SWAP, and 2 ROLL is equivalent to ROT. An unchecked error occurs if there are less than +n items on the data stack.

##### ROOM

ROOM ( -- d )

d is the number of bytes available in the HEAP.

##### ROT

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

Rotates the top three stack cells.

Pronunciation: "rote"

##### ROW->V

ROW->V ( row#\matrix.xpfa -- xvaddr\sep\d.#el )

Returns the vector representation xvaddr\sep\d.#el of the specified row 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 row in a matrix, sep equals the number of rows in the matrix and d.#el equals the 32-bit equivalent of the number of columns 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.

Pronunciation: "row-to-v"

##### ROW.CONCATENATE

ROW.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 rows. The number of columns in the two source matrices must be the same. The destination may be one of the sources.

##### ROW/COL*

ROW/COL* ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

[row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- )

Multiplies each element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

by the corresponding element of the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

and stores the result in the corresponding element of the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3.

The destination row/col may be one of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources.

Pronunciation: "row-or-col-star"
Attributes: S

##### ROW/COL*+

ROW/COL*+ ( r1 \ [row#1\-1] or [-1\col#1]\matrix.xpfa1\

[row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- r1 )

Multiplies the scalar r1 by each element in the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

and adds the result to the corresponding element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

and places the final result in the corresponding element of the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3

Thus for each element, dest  ← src1 + r1*src2. The destination may be either of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources. The scalar r1 is left on the stack.

Pronunciation: "row-or-col-star-plus"
Attributes: S

##### ROW/COL+

ROW/COL+ ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

[row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- )

Adds each element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

to the corresponding element of the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

and stores the result in the corresponding element of the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3

The destination row/col may be one of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources.

Pronunciation: "row-or-col-plus"
Attributes: S

##### ROW/COL-

ROW/COL- ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

[row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- )

Subtracts each element of the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

from the corresponding element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

and stores the result in the corresponding element of the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3

The destination row/col may be one of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources.

Pronunciation: "row-or-col-minus"
Attributes: S

##### ROW/COL->V

ROW/COL->V ( [row#\-1] or [-1\col#]\matrix.xpfa -- xvaddr1\sep\d.#el )

Converts a row/col specified by

[row#\-1] or [-1\col#]\matrix.xpfa

into the equivalent vector representation specified by

xvaddr1\sep\d.#el

To specify a row in the matrix, use row#\-1\matrix.xpfa. To specify a column in the matrix, use -1\col#\matrix.xpfa. The proper xvaddr, separation, and (32-bit) number of elements that specify the vector representation are returned.

Note: 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 double number d.#el is the number of elements in the vector. 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.

Pronunciation: "row-or-col-to-v"

##### ROW/COL.ALL=

ROW/COL.ALL= ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\ 

  [row#2\-1] or [-1\col#2]\matrix.xpfa2 -- flag )

Compares each element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

with the corresponding element of the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

and returns a true flag if all of the corresponding elements are equal. Otherwise returns a false flag.

Pronunciation: "row-or-col-all-equal"

##### ROW/COL.ANY=

ROW/COL.ANY= ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\ 

  [row#2\-1] or [-1\col#2]\matrix.xpfa2 -- flag )

Compares each element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

with the corresponding element of the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

and returns a true flag if any of the corresponding elements are equal. Otherwise returns a false flag.

Pronunciation: "row-or-col-any-equal"

##### ROW/COL.CENTERED

ROW/COL.CENTERED ( [row#\-1] or [-1\col#]\matrix.xpfa -- r )

Finds the arithmetic mean r of the specified row or column in the matrix, and subtracts this value from each element in the row or column, leaving the mean value on the data stack.

Pronunciation: "row-or-col-centered"
Attributes: S

##### ROW/COL.COPY

ROW/COL.COPY ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\ 

  [row#2\-1] or [-1\col#2]\matrix.xpfa2 --  )

Copies the source row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

to the destination row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2.

Pronunciation: "row-or-col-copy"

##### ROW/COL.DELETED

ROW/COL.DELETED ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\matrix.xpfa2 -- )

Copies all but the specified row or column of the source matrix matrix.xpfa1 to the destination specified by matrix.xpfa2. The destination may be the source.

##### ROW/COL.DOT.PRODUCT

ROW/COL.DOT.PRODUCT ( [row#1\-1] or [col#1\-1]\matrix.xpfa1\ 

     [row#2\-1] or [col#2\-1]\matrix.xpfa2 -- r )

r is the dot product of the 2 specified row/cols. The dot product is calculated by multiplying each element in the row/col specified by

[row#1\-1] or [-1\col#1]\ matrix.xpfa1

by the corresponding element in the row/col specified by

[row#2\-1] or [-1\col#2]\ matrix.xpfa2

and summing the results to produce r.

Pronunciation: "row-or-col-dot-product"
Attributes: S

##### ROW/COL.FILL

ROW/COL.FILL ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- )

Stores r into each element of the specified row or column in the matrix.

Pronunciation: "row-or-col-fill"

##### ROW/COL.INSERTED

ROW/COL.INSERTED ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

       [row#2\-1] or [-1\col#2]\matrix.xpfa2 -- )

Inserts the source row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

into the destination matrix specified by matrix.xpfa2 as the row or column specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

The source row/col is unchanged unless it is also the destination. The source may be within the destination matrix.

##### ROW/COL.IS.UNITY.LENGTH

ROW/COL.IS.UNITY.LENGTH ( [row#\-1] or [-1\col#]\matrix.xpfa -- r )

Calculates the length r of the specified row or column and divides each element in the row/column by r so that the row/column has unity length. The old length is left on the stack. The length is defined as the square root of the sum of the squares of the elements in the row or column.

Pronunciation: "row-or-col-is-unity-length"
Attributes: S

##### ROW/COL.MAX

ROW/COL.MAX ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

  [row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- )

Performs the function FMAX on each pair of corresponding elements in the two source row/cols specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

and [row#2\-1] or [-1\col#2]\matrix.xpfa2

and places the result in the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3

The destination may be either of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources.

Pronunciation: "row-or-col-max"

##### ROW/COL.MIN

ROW/COL.MIN ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

  [row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- )

Performs the function FMIN on each pair of corresponding elements in the two source row/cols specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

and [row#2\-1] or [-1\col#2]\matrix.xpfa2

and places the result in the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3

The destination may be either of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources.

Pronunciation: "row-or-col-min"

##### ROW/COL.SUM

ROW/COL.SUM ( [row#\-1] or [-1\col#]\matrix.xpfa -- r )

r is the sum of all of the elements in the specified row or column in the matrix.

Pronunciation: "row-or-col-sum"
Attributes: S

##### ROW/COL.SWAP

ROW/COL.SWAP ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\ 

  [row#2\-1] or [-1\col#2]\matrix.xpfa2 --  )

Swaps the contents of the row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

with the contents of the row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2.

Pronunciation: "row-or-col-swap"

##### ROW/COL.TRANSFORMED

ROW/COL.TRANSFORMED ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\ 

     [row#2\-1] or [-1\col#2]\matrix.xpfa2\ xcfa -- )

xcfa specifies a function that transforms a single floating point number into a floating point result. ROW/COL.TRANSFORMED applies this transformation to each element of the source row or column specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

and places the result in the destination row or column specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

The source row/col can equal the destination.

Pronunciation: "row-or-col-transformed"
Attributes: S

##### ROW/COL.VARIANCE

ROW/COL.VARIANCE ( [row#\-1] or [-1\col#]\matrix.xpfa -- r )

r is the variance, or length squared of the specified row or column in the matrix. It is calculated by performing the dot product of the row or column with itself, which squares each element and sums the squares to produce r.

Pronunciation: "row-or-col-variance"
Attributes: S

##### ROW/COL/

ROW/COL/ ( [row#1\-1] or [-1\col#1]\matrix.xpfa1\

[row#2\-1] or [-1\col#2]\matrix.xpfa2\
[row#3\-1] or [-1\col#3]\matrix.xpfa3 -- )

Divides each element of the source1 row/col specified by

[row#1\-1] or [-1\col#1]\matrix.xpfa1

by the corresponding element of the source2 row/col specified by

[row#2\-1] or [-1\col#2]\matrix.xpfa2

and stores the result in the corresponding element of the destination row/col specified by

[row#3\-1] or [-1\col#3]\matrix.xpfa3

The destination row/col may be one of the sources. If the destination is in the same matrix as one or both of the sources, the destination should not intersect either of the sources.

Pronunciation: "row-or-col-slash"
Attributes: S

##### RP!

RP! ( -- )

Return Stack: ( R: […] – )

Initializes the return stack pointer to be equal to the value in the user variable R0, thus clearing the return stack. The first return stack item will be stored in the two bytes below the value in R0, and the stack grows downward in memory. For example, if R0 = 0x9000, the first stack item is at memory locations 0x8FFE and 0x8FFF. Forces a COLD restart if R0 is not in common RAM.

Pronunciation: "r-p-store"

RS485.RECEIVE ( -- )

Clears bit 4 in PPC (of the PIA) to the logic 0 state. If upper PPC has been configured as an output port, this places the RS485 transceiver in the receive mode. (Make sure that the onboard RS485/RS232 jumper is properly set before attempting to use the RS485 interface).

##### RS485.TRANSMIT

RS485.TRANSMIT ( -- )

Sets bit 4 in PPC (of the PIA) to the logic 1 state. If upper PPC has been configured as an output port, this places the RS485 transceiver in the transmit mode. (Make sure that the onboard RS485/RS232 jumper is properly set before attempting to use the RS485 interface).

Pronunciation: "R-S-four-eighty-five-transmit"

##### RTI.ID

RTI.ID ( -- n )

Returns the interrupt identity code for the real time interrupt. Used as an argument for ATTACH.

Pronunciation: "r-t-i-i-d"

##### S*MATRIX

S*MATRIX ( r\matrix.xpfa1\matrix.xpfa2 -- )

Multiplies the scalar r by each element in the source matrix specified by matrix.xpfa1 and stores the result in the corresponding element of the destination matrix specified by matrix.xpfa2. The source and destination matrices may be the same.

Pronunciation: "s-star-matrix"
Attributes: S

##### S+MATRIX

S+MATRIX ( r\matrix.xpfa1\matrix.xpfa2 -- )

Adds the scalar r to each element in the source matrix specified by matrix.xpfa1 and stores the result in the corresponding element of the destination matrix specified by matrix.xpfa2. The source and destination matrices may be the same.

Pronunciation: "s-plus-matrix"
Attributes: S

##### S-MATRIX

S-MATRIX ( r\matrix.xpfa1\matrix.xpfa2 -- )

Subtracts each element in the source matrix specified by matrix.xpfa1 from the scalar r and stores the result in the corresponding element of the destination matrix specified by matrix.xpfa2. The source and destination matrices may be the same.

Pronunciation: "s-minus-matrix"
Attributes: S

##### S.ROW/COL*

S.ROW/COL* ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- )

Multiplies r by each element in the specified row or column in the matrix and stores the result back into the element.

Pronunciation: "s-row-or-col-star"
Attributes: S

##### S.ROW/COL+

S.ROW/COL+ ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- )

Adds the scalar r to each element in the specified row or column in the matrix and stores the result back into the element.

Pronunciation: "s-row-or-col-plus"
Attributes: S

##### S.ROW/COL-

S.ROW/COL- ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- )

Subtracts each element in the specified row or column in the matrix from r and stores the result back into the element.

Pronunciation: "s-row-or-col-plus"
Attributes: S

##### S.ROW/COL/

S.ROW/COL/ ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- )

Divides r by each element in the specified row or column in the matrix and stores the result back into the element.

Pronunciation: "s-row-or-col-divide"
Attributes: S

##### S.ROW/COL<

S.ROW/COL< ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- flag )

flag is true if r is less than each element in the specified row or column in the matrix. Alternate interpretation: flag is true if all elements in the row or column are greater than or equal to r.

Pronunciation: "s-row-or-col-less-than"

##### S.ROW/COL>

S.ROW/COL> ( r\[row#\-1] or [-1\col#]\matrix.xpfa -- flag )

flag is true if r is greater than each element in the specified row or column in the matrix. Alternate interpretation: flag is true if all elements in row or column are less than or equal to r.

Pronunciation: "s-row-or-col-greater-than"

##### S.V*

S.V* ( r\xvaddr\sep\d.#el -- )

Multiplies r (a scalar) by each element in the vector specified by xvaddr\sep\d.#el.

Pronunciation: "s-v-star"
Attributes: S

##### S.V+

S.V+ ( r\xvaddr\sep\d.#el -- )

Adds r (a scalar) to each element in the vector specified by xvaddr\sep\d.#el.

Pronunciation: "s-v-plus"
Attributes: S

##### S.V-

S.V- ( r\xvaddr\sep\d.#el -- )

Subtracts each element in the vector specified by xvaddr\sep\d.#el from the scalar r.

Pronunciation: "s-v-minus"
Attributes: S

##### S.V.ALL=

S.V.ALL= ( r\xvaddr\sep\d.#el -- flag )

Compares the scalar r to each element of the vector specified by xvaddr\sep\d.#el. flag is TRUE if r is equal to each of the elements in the vector; otherwise, flag is FALSE.

Pronunciation: "s-v-all-equal"

##### S.V.ANY=

S.V.ANY= ( r\xvaddr\sep\d.#el -- flag )

Compares the scalar r to each element of the vector specified by xvaddr\sep\d.#el. flag is TRUE if r is equal to any of the elements in the vector; otherwise, flag is FALSE.

Pronunciation: "s-v-any-equal"

##### S.V/

S.V/ ( r\xvaddr\sep\d.#el -- )

Divides the scalar r by each element in the vector specified by xvaddr\sep\d.#el.

Pronunciation: "s-v-slash"
Attributes: S

##### S.V<

S.V< ( r\xvaddr\sep\d.#el -- flag )

Compares the scalar r to each element of the vector specified by xvaddr\sep\d.#el. flag is true if r is less than each of the elements in the vector; otherwise, flag is FALSE.

Pronunciation: "s-v-less-than"

##### S.V>

S.V> ( r\xvaddr\sep\d.#el -- flag )

Compares the scalar r to each element of the vector specified by xvaddr\sep\d.#el. flag is true if r is greater than each element in the vector; otherwise, flag is false.

Pronunciation: "s-v-greater-than"

##### S/MATRIX

S/MATRIX ( r\matrix.xpfa1\matrix.xpfa2 -- )

Divides the scalar r by each element in the source matrix specified by matrix.xpfa1 and stores the result in the corresponding element of the destination matrix specified by matrix.xpfa2. The source and destination matrices may be the same.

Pronunciation: "s-slash-matrix"
Attributes: S

##### S0

S0 ( -- xaddr )

User variable that contains the 16-bit address which is used by SP! to initialize the data stack pointer. The first cell on the data stack occupies the 2 bytes below the address contained in S0, and the stack grows downward in memory. After changing the contents of S0, the next ABORT or restart loads the value into the stack pointer (the Y register) to change the position of the stack. The data stack is allocated in a 768 byte region in common memory after each COLD restart.

Pronunciation: "s-zero"
Attributes: U

##### S>D

S>D ( n -- d )

Sign-extends a single precision integer to a double precision equivalent.

Pronunciation: "s-to-d"

##### SAVE

SAVE ( -- )

Saves the current memory map so that it may be restored later. Saves the DP, NP, VP, last xnfa in the FORTH vocabulary, and CURRENT.HEAP in a reserved area in EEPROM (0xAE0C to 0xAE1A). RESTORE fetches these quantities and places them in the appropriate user variables to restore the saved state. Useful for dictionary management and for recovery from crashes. Consult the "Program Development Techniques" chapter in the Software Manual for a detailed description of use.

##### SCALE

SCALE ( n1\n2 -- n3 )

Arithmetically (i.e., preserving sign) shifts n1 by n2 bit places to yield signed result n3. If n2 is positive, n1 is shifted left; if n2 is negative, n1 is shifted right. The absolute value of n2 determines the number of bits of shifting. For example, 1 SCALE is equivalent to 2* and -1 SCALE is equivalent to 2/ . There is an unchecked error if the absolute value of n2 is greater than 15.

##### SCAN

SCAN ( xaddr1\u1\char -- xaddr2\u2 )

xaddr2 is the extended address of the first instance of the specified char in the u1 bytes following xaddr1. u2 is the count remaining in the string after the first non-char bytes have been skipped:

 u2 = u1 - (xaddr2 - xaddr1)

u1 and u2 are 16 bit counts. The string may cross a page boundary. SCAN is used by WORD to locate the trailing delimiter of the next word in the input stream.

##### SCI.ID

SCI.ID ( -- n )

Returns the interrupt identity code for the asynchronous serial communications interface. Used as an argument for ATTACH.

Pronunciation: "s-c-i-i-d"

##### SCIENTIFIC

SCIENTIFIC ( -- )

Sets the default printing format used by F. to scientific.

See also F>SCIENTIFIC$##### SCIENTIFIC. SCIENTIFIC. ( r -- ) Prints r using SCIENTIFIC format. See also F>SCIENTIFIC$

Pronunciation: "scientific-dot"
Attributes: M, S

##### SCR

SCR ( -- xaddr )

A user variable containing the block number of the last block (also known as a screen) listed. The name is derived from the first 3 letters of screen.

Pronunciation: "s-c-r"
Attributes: U

##### SELECT.COLUMNS

SELECT.COLUMNS ( n1\...\nN\#cols\matrix.xpfa1\matrix.xpfa2 -- )

Dimensions the destination matrix specified by matrix.xpfa2 to have #cols columns and the same number of rows as the source specified by matrix.xpfa1. Copies #cols columns having column indices n1\…\nN from the source matrix to the destination. The destination may be the source.

##### SEND

SEND ( wd\xmailbox -- )

PAUSEs until the mailbox with extended address xmailbox is empty (i.e., contains 0\0) and then stores the 32-bit message wd in xmailbox. 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).

Attributes: M

##### SERIAL

SERIAL ( -- xresource )

A resource variable associated with the primary serial I/O port. A synonym for SERIAL1.RESOURCE.

##### SERIAL.ACCESS

SERIAL.ACCESS ( -- xaddr )

CAUTION: In multitasking systems using both serial ports SERIAL1 and SERIAL2, the application code should include the command

RELEASE.ALWAYS  SERIAL.ACCESS !

or RELEASE.NEVER SERIAL.ACCESS !

before building the tasks. This prevents contention that can occur if the default RELEASE.AFTER.LINE option is installed in the SERIAL.ACCESS user variable.

Attributes: U

##### SERIAL1.AT.STARTUP

SERIAL1.AT.STARTUP ( -- )

Initializes a flag in EEPROM which installs the primary serial port (serial1) as the default serial port used by the QED-Forth interpreter after each reset or restart. The serial1 port is supported by the 68HC11's on-chip hardware UART.

Implementation detail: Sets the contents of address AE1DH in EEPROM to 0xFF. Upon each reset or restart, the QED-Forth startup routine checks this byte, and contents of 0xFF cause the USE.SERIAL1 routine to be executed.

Pronunciation: "serial-one-at-startup"

##### SERIAL1.RESOURCE

SERIAL1.RESOURCE ( -- xaddr )

A resource variable that mediates access to the primary serial port (serial1) associated with the 68HC11's on-chip hardware UART. Should be accessed only by the words GET ?GET and RELEASE. Initialized to 0\0 by USE.SERIAL1 and USE.SERIAL2 and at each reset or restart.

Pronunciation: "serial-one-resource"

##### SERIAL2.AT.STARTUP

SERIAL2.AT.STARTUP ( u -- | u = baud.rate )

Initializes a flag in EEPROM which installs the secondary serial port (serial2) at the specified baud rate u as the default serial port used by the QED-Forth interpreter after each reset or restart. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). The specified baud rate u must a power of 2 times 75 baud up to a maximum of 9600 baud. Thus the allowed baud rates for this routine are 75, 150, 300, 600, 1200, 2400, 4800, and 9600 baud. The effect of this routine is canceled by executing SERIAL1.AT.STARTUP. Note that the serial2 port can support many more baud rates, but the options have been limited to facilitate setting a reasonable startup baud rate based on a simple implementation as described below. Note also that the maximum baud rate that can be sustained by the serial2 port is less than 9600 baud; see the glossary entry for BAUD2.

Implementation detail: Sets the contents of address AE1DH in EEPROM equal to u/75. Upon each reset or restart, the QED-Forth startup routine checks this byte, and contents equal to an exact power of two cause the USE.SERIAL2 routine to be executed before control is passed to the interpreter or to an autostart routine. Note that USE.SERIAL2 globally enables interrupts during the startup process. If you wish to use the secondary serial port while avoiding this side-effect and maintaining control over the global enabling of interrupts, don't execute SERIAL2.AT.STARTUP. Rather, have your autostart routine explicitly call USE.SERIAL2 after ensuring that all interrupt service routines are properly initialized.

Pronunciation: "serial-two-at-startup"

##### SERIAL2.RESOURCE

SERIAL2.RESOURCE ( -- xaddr )

A resource variable that mediates access to the secondary serial port (serial2). The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). Should be accessed only by the words GET ?GET and RELEASE. Initialized to 0\0 by USE.SERIAL1 and USE.SERIAL2 and at each reset or restart.

Pronunciation: "serial-two-resource"

##### SET.BITS

SET.BITS ( byte1\xaddr -- )

For each bit of byte1 that is set, sets 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.

##### SET.HIGH.CURRENT

SET.HIGH.CURRENT ( byte -- )

For each bit of the input mask byte that is set, turns the corresponding high current driver ON (so that it is sinking current). Bits 0-3 in the input mask byte control the high current drivers named HC0-HC3, respectively. Disables interrupts for 31 cycles (less than 8 microseconds).

##### SET.WATCH

SET.WATCH ( u1\u2\u3\u4\u5\u6\u7\u8 -- )

meaning: ( 100ths.sec\sec\min\hr\day\date\month\yr – )

Sets the battery-operated real-time clock (if present) to the time, day, and date specified by u1 through u8. The stack items and their allowed ranges are:

item   description         range (decimal)
u8   year            0 - 99
u7   month              1 - 12
u6   date              1 - 31
u5   day of week          1 -  7
u4   hour of day           0 - 23
u3   minute after the hour      0 - 59
u2   seconds after the minute   0 - 59
u1   hundredths of seconds      0 - 99

Resolution is better than +/- 1 minute per month. Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years. SET.WATCH uses the top 16 bytes of on-chip RAM at B3F0-B3FF as a scratchpad buffer, and disables interrupts for 0.45 msec while accessing the watch.

##### SIGN

SIGN ( n -- )

If n is negative, inserts a minus sign into the pictured output to the left of the previous character. Used between <# and #>.

Attributes: S

##### SIGNED.D>S

SIGNED.D>S ( d -- n )

n is the signed 16-bit representation of d. FP.ERROR is set if d cannot be represented as a 16-bit signed integer.

Pronunciation: "signed-d-to-s"
Attributes: S

##### SINGLE.STEP

SINGLE.STEP ( -- xaddr )

A user variable that holds a flag. If the flag is true, a definition that has been compiled with TRACE ON stops and enters a special BREAK interpreter before each instruction during the trace. If the flag is false, the BREAK interpreter is not automatically entered before each instruction during the trace. (Even if the flag is false, a keystroke from the terminal may still be used to enter the BREAK mode while the trace is in progress.)

Attributes: U

##### SIZE.OF

SIZE.OF ( -- u )

Compile Time: ( <name> – )

Removes <name> from the input stream, where <name> is a heap structure instance defined using D.INSTANCE: or H.INSTANCE: or V.INSTANCE: (an unchecked error occurs if <name> was not created by one of these three defining words). SIZE.OF returns the size in bytes of <name>. If executing, leaves u on the stack. If compiling, SIZE.OF compiles u as a literal in the current definition.

Attributes: I

##### SKIP

SKIP ( xaddr1\u1\char -- xaddr2\u2 )

Skips the leading specified chars in the string whose first character is at xaddr1 and whose count is u1, returning the string specification xaddr2\u2. xaddr2 is the address of the first byte not equal to char found after searching from xaddr1 to at most xaddr1+u1 . u2 is the count remaining after the leading chars have been skipped:

u2 = u1 - ( xaddr2  - xaddr1 )

u1 and u2 are 16 bit counts. The string may cross a page boundary. This routine is used by WORD to skip leading spaces when parsing the input stream.

##### SKIP>

SKIP> ( xaddr\u1\char -- xaddr\u2 )

Strips the trailing characters specified by char from the string located at xaddr by adjusting the count of the string. Returns the new character count, u2, of the text string with trailing chars removed. The string may cross a page boundary.

Pronunciation: "skip-back"

##### SMUDGE

SMUDGE ( -- )

Toggles (i.e., reverses the state of) the smudge bit in the header of the most recently defined word in the CURRENT vocabulary. If the smudge bit is set, the word cannot be found during a search of the dictionary. The smudge bit is used to prevent execution of incomplete definitions. Used by : ; CODE and END.CODE.

##### SOLVE.EQUATIONS

SOLVE.EQUATIONS ( coefficient.matrix.xpfa\residue.matrix.xpfa\solution.matrix.xpfa -- )

Solves a set of simultaneous linear equations.

Example of use:

If the system of equations is represented by the matrix equation

M X = B

where M is a matrix of coefficients, X is a column matrix of unknown quantities (to be solved for), and B is a column matrix representing the right hand side (residue) of the equations, first define matrices M B and X using the MATRIX: command, initialize M and B, and then execute

' M ' B ' X SOLVE.EQUATIONS

which dimensions the matrix X and stores into it the solution for the unknown quantities.

Attributes: S

##### SP!

SP! ( [...] -- )

Initializes the data stack pointer to be equal to the value in the user variable S0, thus clearing all items off the data stack. The first stack item will be stored in the two bytes below the value in S0, and the stack grows downward in memory. For example, if S0 = 0x9000, the first stack item will be at memory locations 0x8FFE and 0x8FFF. Forces a COLD restart if S0 is not in common RAM.

Pronunciation: "s-p-store"

##### SPACE

SPACE ( -- )

Emits one space character. Equivalent to BL EMIT

Attributes: M

##### SPACES

SPACES ( +byte -- )

Emits +byte spaces. Does nothing if +byte is negative.

Attributes: M

##### SPAN

SPAN ( -- xaddr )

A user variable that contains the number of characters received by the last execution of EXPECT.

Attributes: U

##### SPEED.TO.DUTY

SPEED.TO.DUTY ( steps_per_second\ticks_per_second -- duty_cycle )

Returns an integer representation of a duty cycle which specifies the step rate of the stepper motor. The first input parameter is the integer number of steps per second if full stepping, or the number of halfsteps per second if half stepping. The second input parameter is the integer number of clock ticks per second; the default is 1000 ticks per second. The integer output parameter can be interpreted as a fraction with the radix point to the left of the most significant bit. A 100% duty cycle is represented by 0xFFFF, and this tells the STEP.MANAGER to output a new step pattern on every tick of the interrupt clock (e.g., once per millisecond, corresponding to 1000 (half) steps per second). A duty cycle of 0x8000 means a new step pattern is written to the motor port every other clock tick; a duty cycle of 0x0100 dictates one step every 256 clock ticks; and a duty cycle of 0000 means corresponds to a stopped state with no step pattern updates.

See the high level source file steppers.4th in the Demos_and_Drivers directory of the distribution.

##### SPI.ID

SPI.ID ( -- n )

Returns the interrupt identity code for the synchronous serial peripheral interface (SPI). Used as an argument for ATTACH. Note that the SPI communicates with the onboard 12 bit A/D and 8 bit D/A if they are installed.

Pronunciation: "s-p-i-i-d"

##### SPI.OFF

SPI.OFF ( -- )

Disables the serial peripheral interface (SPI) by clearing the SPI enable (SPE) bit in the SPI control register (SPCR). After execution of this routine, PORTD pins PD2-PD5 may be used as standard digital I/O subject to the data direction specified in the PORTD.DIRECTION register.

Pronunciation: "init-S-P-I"

##### SPI.RESOURCE

SPI.RESOURCE ( -- xaddr )

A resource variable associated with the serial peripheral interface (SPI) which is used for data transfer to and from the 12 bit analog to digital converter and 8 bit digital to analog converter. Should be accessed only by the words GET ?GET and RELEASE. Initialized to 0\0 by INIT.SPI and INIT.A/D12&DAC and at each reset or restart. SPI.RESOURCE is automatically invoked by many of the A/D12 and DAC device driver routines.

Pronunciation: "S-P-I-resource"

##### SQRT(2)

SQRT(2) ( -- r )

Places the floating point representation of the square root of 2 (1.41421) on the stack.

Pronunciation: "square-root-of-two"

##### STACK.FRAME

STACK.FRAME ( +n -- [+n bytes]\xaddr )

Reserves +n bytes of room on the data stack and leaves xaddr that points to the top (lowest in memory) reserved byte of the data stack frame. xaddr is equal to the stack pointer before the xaddr is placed on the stack. xaddr is the base address of the stack frame. If +n is odd it is incremented to reserve an integer number of cells (of two bytes each) on the stack. STACK.FRAME is typically used to create a temporary variable space within colon definitions so that re-entrant code may be written. FRAME.DROP is used to drop the stack frame off the data stack.

##### STANDARD.MAP

STANDARD.MAP ( -- )

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

##### STANDARD.RESET

STANDARD.RESET ( -- )

Undoes the effect of the COLD.ON.RESET command so that subsequent resets will result in the standard warm-or-cold startup sequence. Implementation detail: sets the flag at location AE1CH in EEPROM to 0xFF.

##### START.HEAP

START.HEAP ( -- xaddr )

A variable that holds the extended address of the start of the current heap. The xaddr left on the stack by START.HEAP is equal to CURRENT.HEAP - 4. Initialized by IS.HEAP.

##### START.TIMESLICER

START.TIMESLICER ( -- )

Starts the timeslice clock and begins timeslice multitasking. Initializes the OC2 interrupt vector (if it wasn't already initialized) so that the multitasking executive/elapsed-time clock routine services the interrupt. Enables the OC2 interrupt mask and globally enables interrupts by clearing the I bit in the condition code register of each built task.

Notes:

1. The default timeslice clock period of 5 msec can be changed with the command *100US=TIMESLICE.PERIOD.

2. START.TIMESLICER does not initialize the value in TIMESLICE.COUNT; execute INIT.ELAPSED.TIME if you wish to initialize the clock count to 0\0.

3. After a restart, the system is configured so that timeslice multitasking can begin at any time; if no other tasks have been built, the main QED-Forth task is the only task in the task loop.

4. The timeslice clock must be running to use the BENCHMARK: function.

5. The timeslicer's interrupt service routine disables interrupts for the duration of a task switch which requires 25 microseconds plus 3.25 microseconds for each ASLEEP task encountered in the task list.

##### STATE

STATE ( -- xaddr )

A user variable that indicates the compilation state. If the contents of STATE equal 0, the system is in execution mode. If the contents equal -1, the system is in compilation mode. STATE is modified by the commands [ and ].

Attributes: U

##### STATUS

STATUS ( -- xaddr | xaddr is also the task's xtask.id )

Attributes: U

##### STEP.MANAGER

STEP.MANAGER ( -- )

Expects the base address of the STATUS.ARRAY in the Y register. Based on the information in the STATUS.ARRAY and the RAMP.ARRAY, for each enabled motor STEP.MANAGER writes the appropriate step pattern at the specified duty cycle to the motor port to attain the speed specified in the motor's RAMP.ARRAY. This function is meant to be called from a periodic interrupt service routine typically associated with an output compare (OC) interrupt; the default time base is once per millisecond generated by the OC3 interrupt, with a resulting maximum speed of 1000 full- or half-steps per second. This assembly coded routine executes in approximately 120 µs per enabled stepper motor. Thus running four stepper motors at a maximum speed of 1000 full- or half-steps per second requires approximately half of the 68HC11's available time (480 µs interrupt service time every 1000 µs).

See also the high level source file steppers.4th in the Demos_and_Drivers directory of the distribution. CAUTION: The presence of other interrupt service routines can affect the timing of the step manager, and may affect the smoothness of the stepper motor operation

##### STOP.TIMESLICER

STOP.TIMESLICER ( -- )

Stops the multitasker's timeslice clock by disabling the local OC2 timer interrupt mask. Cooperative (PAUSE-invoked) task switching is not affected.

Also see START.TIMESLICER. Note that this command also stops QED-Forth's elapsed-time clock, and that the timing feature of the BENCHMARK: command cannot be used unless the timeslice clock is running.

##### STRING->

STRING-> ( u1\u2 -- u3 )

Adds a named member to the structure being defined and reserves room for a counted string in the structure. u2 is the number of characters in the string; u2+1 bytes are reserved to allow room for the string's count byte. 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: "string"
Attributes: D

##### STRUCT->

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

Adds a named member to the structure being defined and reserves room for a (sub)structure of size u2 bytes in the structure being defined. 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: "struct"
Attributes: D

##### STRUCTS->

STRUCTS-> ( u1\u2\u3 <name> -- u4 )

Adds a named member to the structure being defined and reserves room for u2 (sub)structures 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 size of the (sub)structure, and u4 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: "structs"
Attributes: D

##### STRUCTURE.BEGIN:

STRUCTURE.BEGIN: ( <name> -- xpfa\0 )

Begins a structure definition and creates a named constant <name> which, when executed, returns the size of the structure in bytes.

See also the "Structures" chapter in the Software Manual for a detailed description and examples of use

Implementation detail: <name>'s parameter field is at xpfa, and its initial contents equal 0. STRUCTURE.BEGIN: leaves the xpfa and the initial size on the stack. The size is incremented throughout the structure's definition. STRUCTURE.END stores the total size of the structure into the xpfa of the structure constant <name>.

Pronunciation: "structure-begin"
Attributes: D

##### STRUCTURE.END

STRUCTURE.END ( xpfa\u -- | u is the structure's size )

Marks the end of a structure definition. Stores u, the total number of bytes in the structure being defined, into the xpfa of the structure constant created by STRUCTURE.BEGIN:.

Attributes: D

##### SWAP

SWAP ( w1\w2 -- w2\w1 )

Exchanges the top two stack cells.

##### SWAP.ARRAYS

SWAP.ARRAYS ( array.xpfa1\array.xpfa2 -- )

Interchanges the contents of the parameter fields of the two specified arrays and leaves the heap undisturbed, thus rapidly swapping the two arrays.

##### SWAP.MATRIX

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

Interchanges the contents of the parameter fields of the two specified matrices and leaves the heap undisturbed, thus rapidly swapping the two matrices.

##### SWI.ID

SWI.ID ( -- n )

Returns the interrupt identity code for the software interrupt (SWI). Used as an argument for ATTACH.

Also see the SWI instruction in the assembler glossary.

Pronunciation: "s-w-i-i-d"

##### TAB.WIDTH

TAB.WIDTH ( -- xaddr )

A user variable that contains the number of spaces that EXPECT places in the TIB to replace each incoming TAB character (ascii 09). Replacing tabs with spaces ensures that tab-delimited words can be interpreted. The default is 4.

Pronunciation: "tab-width"
Attributes: U

TASK'S.USER.VAR ( xaddr1\xtask.id -- xaddr2 )

ASLEEP  STATUS  OTHER.TASK  TASK'S.USER.VAR  !

TASK: ( xtask.id <name> -- )

Removes the next <name> from the input stream and creates an XCONSTANT that, when executed, leaves the task identifier xtask.id on the stack. xtask.id is the base xaddress of the user area of the new task being defined. An error is issued if xtask.id is not in common RAM. xtask.id is also referred to as the task's STATUS address.

Attributes: D

##### TEN

TEN ( -- r )

Pushes the floating point number 10. onto the data stack.

##### THEN

THEN ( -- )

Synonym for ENDIF . Used inside a colon definition to mark the end of an IF … ELSE … THEN or IF … THEN conditional structure. The word following THEN is executed after the IF or ELSE (if present) part of the conditional executes. An error is issued if THEN is not paired with IF or ELSE in a colon definition.

Attributes: C, I

##### THIS.PAGE

THIS.PAGE ( -- byte )

Returns the contents of the page latch which indicates the current page. THIS.PAGE is equivalent to (PAGE.LATCH) (C@)

##### TIB

TIB ( -- xaddr | xaddr is the start of the terminal input buffer )

Returns the starting xaddr of the terminal input buffer. Equivalent to UTIB X@. The terminal input buffer may be on any page, but may not cross a page boundary. The default size of the terminal input buffer is 96 bytes.

Attributes: U

##### TIMER.OVERFLOW.ID

TIMER.OVERFLOW.ID ( -- n )

Returns the interrupt identity code for the free-running timer overflow interrupt. Used as an argument for ATTACH.

Pronunciation: "timer-overflow-i-d"

##### TIMESLICE.COUNT

TIMESLICE.COUNT ( -- xaddr )

Returns the extended address of the system variable TIMESLICE.COUNT. It contains a 32-bit count of the number of clock ticks on the timeslicer clock. The period of the clock is set by *100US=TIMESLICE.PERIOD. TIMESLICE.COUNT must only be read using the atomic read word |2@|, i.e.

TIMESLICE.COUNT |2@|

##### TO

TO ( [n] or [r] or [xaddr] or [d] -- | depends on type of self fetchers or locals )

Compile Time: ( <name> – )

Stores a value into the named self-fetching or local variable. Removes <name> from the input stream. If in compilation mode, compiles code that, when later executed, will store the value on top of the stack into the self-fetching or local variable. If in execution mode, stores the value on top of the stack into the self-fetching or local variable. If <name> represents a 32-bit self-fetching variable (i.e., created by REAL: DOUBLE: or XADDR:) or a 32-bit local variable (i.e., one whose name begins with D& or F& or X&), then a 32-bit value is removed from the stack and stored; otherwise, a 16-bit value is removed from the stack and stored.

Attributes: I

##### TO.FLASH

TO.FLASH ( xaddr1\xaddr2\u -- success_flag | xaddr1=src, xaddr2=dest, u = byte count )

Transfers num bytes (0 ≤ num ≤ 65,535) starting at the specified source extended address, to the specified destination extended address in flash. The source may be anywhere in memory; it may even be in the flash which is being programmed. The destination must be in flash. Returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. Reasons for failure include improper DIP switch settings, or a destination that is not in a programmable page in flash memory. Recall that, on a QED-Flash Board, DIP switches number 2, 3, and 4 must be ON to allow writes to the flash. (If any locations in the flash are programmed more than 10,000 times, the cell may wear out causing a failure flag to be returned). Assuming that the standard 256 Kbyte flash is present on the board, writable flash pages include pages 4, 5 and 6 for the standard map, and pages 1, 2, and 3 for the download memory map. Page 7 is always in flash and writable; it provides an excellent location for data or graphics storage. Page 0x0D is also writeable flash, and is often used to hold kernel extension code. This function uses the 68HC11's on-chip RAM at 0xB200 to 0xB3CF to manage the write to the flash (the real-time clock and C/Forth interrupt stack reserve the bytes at 0xB3D0 to 0xB3FF). The remaining on-chip RAM at 0xB000 to 0xB1FF remains available to the user. Caution: the prolonged disabling of interrupts by TO.FLASH can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.

##### TO.HEAP

TO.HEAP ( xhandle -- flag )

If xhandle is a valid 32-bit handle in the current heap, the heap item associated with the xhandle is returned to the heap (de-allocated), the heap is compacted, and a true flag is returned. If xhandle is not a valid handle in the current heap, no action is taken and a false flag is returned.

##### TOGGLE.BITS

TOGGLE.BITS ( byte1\xaddr -- )

For each bit of byte1 that is set, reverses the state of 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.

##### TRACE

TRACE ( -- xaddr )

A user variable that contains a flag. If true, this flag causes a call to a trace routine to be compiled before each compiled word in a colon or code definition. The trace instruction (a headerless routine called DO.TRACE) can facilitate debugging. If a definition has been compiled while TRACE is ON, then when the word is executed (if DEBUG is ON) the compiled trace routine prints out the name of each called subroutine in the definition as it executes, along with the stack picture after that step in the definition. If DUMP.REGISTERS is ON, the contents of the 68HC11's registers are printed; this aids in the debugging of assembly coded routines. If SINGLE.STEP is ON, the BREAK mode is entered after each step in the definition. The BREAK mode is also entered if any character is received by QED-Forth while a trace is in progress. To add even more flexibility and power to the debugger, the first thing that DO.TRACE does is to execute the code whose xcfa is stored in the user variable TRACE.ACTION. The default action is NO.OP, but the programmer can define any action and install it using IS.TRACE.ACTION; see IS.TRACE.ACTION for further details.

Attributes: U

##### TRAILING.ZEROS

TRAILING.ZEROS ( -- xaddr )

A user variable that contains a flag. If the flag is false, trailing zeroes are not printed when a floating point number is displayed in fixed or floating format. If true, trailing zeros are displayed.

See also F>FIXED$and F>FLOATING$

Attributes: U

##### TRANSFER.HEAP.ITEM

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

Copies the heap item specified by xhandle1 in the current heap into the heap whose CURRENT.HEAP is equal to xaddr. If the operation is successful, returns the 32-bit handle xhandle2 of the new heap item; if unsuccessful, does nothing and returns 0\0. To copy a heap item within a single heap, see DUP.HEAP.ITEM.

##### TRANSFORM.MATRIX

TRANSFORM.MATRIX ( matrix.xpfa1\matrix.xpfa2\xcfa -- )

xcfa specifies a unary operator that transforms a floating point number into another floating point number. TRANSFORM.MATRIX applies the specified transformation to each element of the source matrix specified by matrix.xpfa1 and places the result in the destination matrix specified by matrix.xpfa2. The source and destination matrices may be the same.

For example, to replace each element in a matrix named MAT.A with its base 10 logarithm, execute:

' MAT.A  XDUP  CFA.FOR  FLOG10  TRANSFORM.MATRIX

Pronunciation: "transform-matrix"
Attributes: S

##### TRANSMITTING

TRANSMITTING ( -- xaddr )

Returns the extended address of a system variable that holds a flag. The flag is true if the secondary serial port (serial2) is in the process of transmitting a character. If the serial2 transmitter is active, the TRANSMITTING flag stays true until the serial2 output buffer is empty. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output).

##### TRANSPOSED

TRANSPOSED ( matrix.xpfa1\matrix.xpfa2 -- )

Properly dimensions the destination matrix and places the transpose of the source matrix.xpfa1 in the destination matrix.xpfa2. (Matrix transposition changes rows in the source into columns in the destination, and columns in the source into rows in the destination). The source and the destination may be the same.

Attributes: S

##### TRUE

TRUE ( -- flag | flag = -1 )

Puts a boolean true flag equal to -1 on the data stack.

##### TUCK

TUCK ( w1\w2 -- w2\w1\w2 )

Copies the top data stack cell to below the next data stack cell. TUCK is equivalent to SWAP OVER.

##### TYPE

TYPE ( xaddr\cnt -- )

If cnt is greater than zero, emits cnt characters beginning at location xaddr. xaddr is typically the beginning of a text string and cnt is the text string's character count. There is an unchecked error if cnt is outside the range 0 to 255. The string may cross a page boundary.

Attributes: M

##### TYPE.END

TYPE.END ( u1\u2\u3 -- max{u1,u2,u3} )

Marks the end of a TYPE.OF: construct within a structure definition.

Attributes: D

##### TYPE.OF:

TYPE.OF: ( u -- u\u\u )

Marks the beginning of a TYPE.OF: construct within a structure definition. This allows fields to be defined for variant data types. Each variant type is designated by an OR.TYPE.OF: declaration, and the TYPE.OF: construct is terminated by TYPE.END. For example, the following structure allows a member to be referred to either as a 32-bit xhandle or as a separate handle and page:

STRUCTURE.BEGIN: HEAP.STRUCTURE.PF
TYPE.OF:
XHNDL->   +XHANDLE
OR.TYPE.OF:
PAGE->   +HNDL.PAGE
TYPE.END
STRUCTURE.END

Pronunciation: "type-of"
Attributes: D

##### U*/MOD

U*/MOD ( u1\u2\u3 -- u4\u5 | do u1*u2/u3; u4 = remainder; u5 = quotient )

Multiplies two unsigned integers u1 and u2 producing an intermediate unsigned double number result which is divided by unsigned integer u3 to yield an integer remainder u4 and quotient u5. An unchecked error occurs on overflow. Division by zero (u2=0) yields u4 = u5 = -1 .

Pronunciation: "u-star-slash-mod"

##### U.

U. ( u -- )

Prints unsigned integer u with no leading spaces and 1 trailing space.

Pronunciation: "u-dot"
Attributes: M, S

##### U.INVERTED

U.INVERTED ( matrix.xpfa1\matrix.xpfa2 -- )

Inverts an upper triangular matrix specified by matrix.xpfa1 and puts the inverse in the destination matrix.xpfa2. Ignores the lower half of the source matrix so it doesn't matter if the elements are not truly zero. The source and destination may be the same.

Pronunciation: "u-inverted"
Attributes: S

##### U/

U/ ( u1\u2 -- u3 | u3 = u1/u2 )

Divides unsigned integer u1 by unsigned integer u2, giving the unsigned integer quotient u3. Division by 0 (u2 = 0) results in a quotient of -1. This is the fastest integer divide command.

Pronunciation: "u-slash"

##### U/MOD

U/MOD ( u1\u2 -- u3\u4 | u3 = remainder, u4 = quotient )

Divides unsigned integer u1 by u2, giving the unsigned integer quotient u4 and remainder u3. Division by 0 (u2 = 0) results in a quotient of -1 and an indeterminant remainder. This is the fastest integer divide with remainder.

Pronunciation: "u-slash-mod"

##### U2/

U2/ ( u1 -- u2 | u2 = u1 / 2 )

Divides the unsigned number u1 by 2 giving u2.

Pronunciation: "u-two-slash"

##### U<

U< ( u1\u2 -- flag )

Flag is TRUE if unsigned integer u1 is less than unsigned integer u2 and FALSE otherwise.

Pronunciation: "u-less-than"

##### U>

U> ( u1\u2 -- flag )

Flag is TRUE if unsigned integer u1 is greater than unsigned integer u2 and FALSE otherwise.

Pronunciation: "u-greater-than"

##### U>D

U>D ( u -- ud )

Converts unsigned integer u to its double number equivalent ud by placing a 0 on the data stack above u.

Pronunciation: "u-to-d"

##### U?KEY

U?KEY ( -- xaddr )

A user variable that contains the extended code field address of the ?KEY routine.

Pronunciation: "u-question-key"
Attributes: U

##### UABORT

UABORT ( -- xaddr )

A user variable that contains the extended code field address of the user-supplied abort routine that is executed if the CUSTOM.ABORT flag is TRUE. If CUSTOM.ABORT is FALSE, ABORT executes the default (ABORT) routine. UABORT is initialized by COLD to contain the xcfa of (ABORT).

Pronunciation: "u-abort"
Attributes: U

##### UD*S

UD*S ( ud1\u -- ud2 | ud2 = ud1 * u )

Multiplies unsigned double number ud1 by unsigned single precision number u giving the unsigned double number result ud2. An unchecked error occurs on overflow.

Pronunciation: "u-d-star-s"

##### UD.R

UD.R ( ud\+byte -- | +byte = width )

Prints the unsigned double number ud 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.

Pronunciation: "u-d-dot-r"
Attributes: M, S

##### UEMIT

UEMIT ( -- xaddr )

A user variable that contains the extended code field address of the EMIT routine.

Pronunciation: "u-emit"
Attributes: U

##### UERROR

UERROR ( -- xaddr )

A user variable that contains the extended code field address of the error routine that is executed if the CUSTOM.ERROR flag is TRUE. If CUSTOM.ERROR is FALSE, all system errors call the default (ERROR) routine which prints descriptive error messages. UERROR is initialized by COLD to contain the xcfa of a simple default error handler that prints the hexadecimal system error number and executes ABORT. Consult the error message appendix in the Software Manual.

See also ((ERROR)), (ERROR), CUSTOM.ERROR, and ABORT.

Pronunciation: "u-error"
Attributes: U

##### UFIRST

UFIRST ( -- xaddr )

A user variable that holds the extended address of the first byte of the first block buffer. Executing UFIRST X@ places the xaddress of the first byte of the block buffers on the stack. Initialized by BLOCK.BUFFERS.

Pronunciation: "u-first"
Attributes: U

##### UFIXX

UFIXX ( r -- u )

Rounds the positive floating point number r to the nearest unsigned integer u. Equivalent to DFIXX D>S. Overflow errors are not checked.

Attributes: S

##### UFLOT

UFLOT ( u -- r )

Converts the 16 bit unsigned integer u to its floating point representation r.

Pronunciation: "u-float"
Attributes: S

##### UKEY

UKEY ( -- xaddr )

A user variable that contains the extended code field address of the KEY routine.

Pronunciation: "u-key"
Attributes: U

##### ULIMIT

ULIMIT ( -- xaddr )

A user variable that contains the extended address of the last+1 byte in the last block buffer. Initialized by BLOCK.BUFFERS.

Pronunciation: "u-limit"
Attributes: U

##### UM*

UM* ( u1\u2 -- ud | ud = u1 * u2 )

Multiplies unsigned integers u1 and u2 giving the unsigned double precision product ud.

Pronunciation: "u-m-star"

##### UM/MOD

UM/MOD ( ud1\u1 -- u2\ud2 | u2 = remainder, ud2 = quotient )

Divides unsigned double number ud1 by unsigned integer u1 to give an unsigned single-precision remainder u2 and an unsigned double number quotient ud2. Division by 0 (u1=0) yields u2 = -1 and ud2 = -1.

Pronunciation: "u-m-slash-mod"

##### UMAX

UMAX ( u1\u2 -- [u1] or [u2] )

Retains the greater of two unsigned integers and drops the other.

Pronunciation: "u-max"

##### UMIN

UMIN ( u1\u2 -- [u1] or [u2] )

Retains the lesser of two unsigned integers and drops the other.

Pronunciation: "u-min"

##### UMOD

UMOD ( u1\u2 -- u3 | u3 = remainder of u1/u2 )

Divides unsigned integer u1 by unsigned integer u2, giving the unsigned remainder u3. Division by zero results in an indeterminant remainder. This is the fastest modulus function.

Pronunciation: "u-mod"

##### UNDERFLOW

UNDERFLOW ( -- )

Sets the user variable FP.ERROR to 1 to indicate an underflow error.

##### UNIQUE.MSG

UNIQUE.MSG ( -- xaddr )

A user variable that contains a flag. If the flag is true (the default condition), BEEP is executed and a warning message is printed each time a word is defined that already exists in the CURRENT or CONTEXT vocabularies. If the flag is false, no warning is issued when non-unique words are added to the dictionary.

Pronunciation: "unique-message"

##### UNLOOP

UNLOOP ( -- )

Return Stack: ( R: w1\w2 – | discards the loop limit and index )

Removes the top two cells from the return stack. If you need to immediately EXIT a word definition from inside a DO…LOOP, call UNLOOP to discard the loop index and limit before executing EXIT to exit the definition. To exit a definition from within nested do loops, execute one UNLOOP for each level of nesting. Make sure that there are no additional items on the return stack (e.g., resulting from a >R command). UNLOOP is a synonym for XR>DROP which drops two cells from the return stack.

Attributes: C

##### UNTIL

UNTIL ( flag -- )

Used inside a colon definition to mark the end of a BEGIN … UNTIL loop structure which terminates based on the value of flag. If flag is true, the loop terminates and execution continues with the word following UNTIL. If flag is false, looping continues and execution passes to the word following BEGIN. Use as:

BEGIN    ... words to be executed ...
flag UNTIL

An error is issued if BEGIN and UNTIL are not properly paired within a definition.

Attributes: C, I

##### UP

UP ( -- xhandle | xhandle contains 16-bit user pointer )

Places on the stack the 32-bit extended address that contains the 16-bit base address of the current task's user area. Executing UP @ is equivalent to executing (STATUS) ; both return the 16-bit base address (in common memory) of the current task.

Pronunciation: "u-p"

UPAD ( -- xaddr )

User variable that holds the 32 bit xaddr of PAD. The contents of UPAD must point to modifiable RAM, and there must be at least 32 bytes of RAM below PAD for number/string conversion. PAD may be on any page, but may not cross a page boundary. To change the location of PAD, store the new xaddress into UPAD using X!.

Attributes: U

##### UPDATE

UPDATE ( -- )

Marks the current buffer as updated.

Implementation detail: Sets the top bit in the buffer's 32-bit status flag. The current buffer is pointed to by PREV.

##### UPDATE.DISPLAY

UPDATE.DISPLAY ( -- )

Writes the contents of the DISPLAY.BUFFER to the LCD display. When finished, leaves the display cursor pointing at the first position in the first line. 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.

##### UPDATE.DISPLAY.LINE

UPDATE.DISPLAY.LINE ( n -- | n = line# )

Writes the contents of the specified line number n in the DISPLAY.BUFFER to the LCD display. n is zero-based, and is clamped to a maximum of 1 less than LINES/DISPLAY. Writes CHARS/DISPLAY.LINE characters to the display. When finished, leaves the display cursor pointing at the first position in the line following n. For character displays, the cursor is blanked during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. The line# n1 follows the same rules explained in the description of BUFFER.POSITION: 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#. Intermittently disables interrupts for 28 cycles (7 microseconds) per byte to implement clock stretching.

##### UPOCKET

UPOCKET ( -- xaddr )

User variable that holds the 16-bit addr of POCKET which is in common memory. To change the location of POCKET, store the new xaddress into UPOCKET using !. Note that FIND executes COLD if POCKET is not in the common RAM.

Pronunciation: "u-pocket"
Attributes: U

##### UPPER.CASE

UPPER.CASE ( x$addr -- x$addr )

Converts all of the characters in the counted string at x\$addr to upper case letters. The string may not cross a page boundary.

##### URANGE

URANGE ( u1\u2\u3 -- u1\flag )

Flag is TRUE if u1 is greater than or equal to u2 and less than or equal to u3. Otherwise flag is FALSE. Uses unsigned comparison.

Pronunciation: "u-range"

##### URANGE.OF

URANGE.OF ( u1\u2\u3 -- [u1] or [] )

Used inside a CASE … ENDCASE structure to mark the beginning of a conditional statement. If u2 ≤ u1 ≤ u3 (using unsigned math) then u1, u2, and u3 are dropped and execution continues with the words between URANGE.OF and ENDOF and then skips to the word after ENDCASE. Otherwise, u2 and u3 are dropped and execution continues after the next ENDOF. Use as:

n1 CASE
u2 u3 URANGE.OF executed if n1 in range (u2,u3)    ENDOF
u4 u5 URANGE.OF executed if n1 in range (u4,u5)   ENDOF
words to be executed if not in range (u2,u3) or (u4,u5)
ENDCASE

An error is issued if URANGE.OF and ENDOF are not properly paired.

Pronunciation: "u-range-of"
Attributes: C, I

UREAD/WRITE ( -- xaddr )

A user variable that contains the extended code field address of the mass memory read/write word called by the command READ/WRITE. Its default contents equal the xcfa of the ram disk utility.

Attributes: U

##### USE

USE ( -- xaddr )

A user variable containing the extended address of the next block buffer to use (that is, the least most recently accessed buffer).

Attributes: U

##### USE.PAGE

USE.PAGE ( page -- )

Sets up a useful default memory map in the specified page of RAM, and places the heap area in the top 14.5K of page fifteen and the variable area in common RAM. The locations of the user area, data stack, return stack, TIB, POCKET and PAD are not changed (they are typically in the common RAM). The memory map is initialized as follows:

20 Kbyte definitions area starts at 0x0000 on the specified page
12 Kbyte name area starts at 0x5000 on the specified page
Variable area starts at 0x8E00 in common memory
14.5 Kbyte heap occupies 0x4600\F-0x7FFF\F

The dictionary and names areas are on the specified page and may be write-protectable (pages 4, 5, 6, and 7 are write-protectable). The heap is on page 0x0F (non-write-protectable RAM) and the variable area is in common RAM, so the variable and heap areas will never be mistakenly ROMmed or write protected. This routine is provided as a convenience to users who need to set up a reasonable memory map immediately after start up. It is strongly recommended that the programmer execute

ANEW <name>

immediately after using this word. Doing so will properly reset the necessary pointers when forgetting compiled words during debugging. Implementation detail example: Executing 4 USE.PAGE is equivalent to:

HEX   0000  04  DP  X!         5000  04  NP X!
8E00  00  VP  X!   4600  0F   7FFF  0F  IS.HEAP

##### USE.SERIAL1

USE.SERIAL1 ( -- )

Installs the primary serial port (serial1) as the serial link used by the QED-Forth interpreter and called by EMIT, ?KEY, and KEY. The serial1 port is associated with the 68HC11's on-chip hardware UART. Stores the xcfa of KEY1 in UKEY, the xcfa of ?KEY1 in U?KEY, and the xcfa of EMIT1 in UEMIT. Thus the vectored routines KEY, ?KEY, and EMIT will automatically execute the serial1 routines KEY1, ?KEY1, and EMIT1 respectively. Initializes the resource variable SERIAL1.RESOURCE to 0\0, and initializes the resource variable associated with the prior serial channel in use (typically either SERIAL1.RESOURCE or SERIAL2.RESOURCE) to 0\0. Does not disable the serial2 port.

Pronunciation: "use-serial-one"

##### USE.SERIAL2

USE.SERIAL2 ( -- )

Installs the secondary serial port (serial2) as the serial link used by the QED-Forth interpreter and called by EMIT, ?KEY, and KEY, calls INIT.SERIAL2 to initialize the serial2 port, and globally enables interrupts to allow the serial2 port to operate. The serial2 port is supported by QED-Forth's software UART using hardware pins PA3 (input) and PA4 (output). USE.SERIAL2 stores the xcfa of KEY2 in UKEY, the xcfa of ?KEY2 in U?KEY, and the xcfa of EMIT2 in UEMIT. Thus the vectored routines KEY, ?KEY, and EMIT will automatically execute the serial2 routines KEY2, ?KEY2, and EMIT2 respectively. Initializes the resource variable SERIAL2.RESOURCE to 0\0, and initializes the resource variable associated with the prior serial channel in use (typically either SERIAL1.RESOURCE or SERIAL2.RESOURCE) to 0\0. Does not disable the serial1 port.

Pronunciation: "use-serial-two"

##### USER

USER ( +byte <name> -- | +byte = offset from user area base address )

Removes the next <name> from the input stream and creates a user variable called <name> which when executed places on the stack an extended address equal to the user base address (i.e., the value in UP) plus the specified offset +byte. Use as:

+byte USER <name>

The user area holds system variables. The kernel word #USER.BYTES returns the number of bytes in the user area that are already used by the QED-Forth system. Thus when defining a new user variable, +byte should be greater than or equal to #USER.BYTES and less than 255 (the maximum size of the user area).

Attributes: D

##### UTIB

UTIB ( -- xaddr )

User variable that holds the 32 bit xaddr of the TIB (terminal input buffer). To change the location of TIB, store the new xaddress into UTIB using X!. The terminal input buffer may be on any page, but may not cross a page boundary.

Pronunciation: "u-t-i-b"
Attributes: U

##### V*

V* ( xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el -- )

Multiplies each element of the source1 vector specified by xvaddr1\sep1\d.#el with the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el and places the result in the corresponding element of the destination vector specified by xvaddr3\sep3\d.#el. The destination vector may be one of the source vectors.

Pronunciation: "v-star"
Attributes: S

##### V*+

V*+ ( r1\xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el -- r1 )

Multiplies the scalar r1 by each element in the source2 vector specified by xvaddr2\sep2\d.#el and adds the result to the corresponding element in the source1 vector specified by xvaddr1\sep1\d.#el, and places the final result in the corresponding element of the destination vector specified by xvaddr3\sep3\d.#el. Thus for each element,

dest <- src1 + r1*src2

The destination vector may be one of the source vectors. The scalar r1 is left on the stack.

Pronunciation: "v-star-plus"
Attributes: S

##### V+

V+ ( xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el -- )

Adds each element of the source1 vector specified by xvaddr1\sep1\d.#el with the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el and places the result in the corresponding element of the destination vector specified by xvaddr3\sep3\d.#el. The destination vector may be one of the source vectors.

Pronunciation: "v-plus"
Attributes: S

##### V,

V, ( w -- )

Stores w at the next available location in the variable area and increments the variable pointer VP by 2. An error occurs if w is not correctly stored; e.g. if VP does not point to RAM. An error occurs if the V, operation causes VP 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: "v-comma"

##### V-

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

Subtracts each element of the source2 vector specified by xvaddr2\sep2\d.#el from the corresponding element in the source1 vector specified by xvaddr1\sep1\d.#el and places the result in the corresponding element of the destination vector specified by xvaddr3\sep3\d.#el. The destination vector may be one of the source vectors.

Pronunciation: "v-minus"
Attributes: S

##### V.ALL=

V.ALL= ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- flag )

flag is true if each element in the source1 vector specified by xvaddr1\sep1\d.#el is equal to the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el.

Pronunciation: "v-all-equal"

##### V.ANY=

V.ANY= ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- flag )

flag is true if any element in the source1 vector specified by xvaddr1\sep1\d.#el is equal to the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el.

Pronunciation: "v-any-equal"

##### V.COPY

V.COPY ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- )

Copies the contents of the source vector specified by xvaddr1\sep1\d.#el to the destination vector specified by xvaddr2\sep2\d.#el.

Pronunciation: "v-copy"

##### V.FILL

V.FILL ( r\xvaddr\sep\d.#el -- )

Stores r into each element of the vector specified by xvaddr\sep\d.#el.

Pronunciation: "v-fill"

##### V.INSTANCE:

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

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

<structure.name>  V.INSTANCE:  <name>

where <structure.name> was defined using

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

Executing <structure.name> leaves the structure size n on the stack, and V.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 variable pointer VP so that it points to a new page.

Pronunciation: "v-instance"
Attributes: D

##### V.MAX

V.MAX ( xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el -- )

Performs the function FMAX on each pair of corresponding elements in the 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 one of the sources.

Pronunciation: "v-max"

##### V.MIN

V.MIN ( xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el -- )

Performs the function FMIN on each pair of corresponding elements in the 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 one of the sources.

##### V.SUM

V.SUM ( xvaddr\sep\d.#el -- r | r = sum of elements in vector )

Returns the sum of elements r in the vector specified by xvaddr\sep\d.#el.

Pronunciation: "v-sum"
Attributes: S

##### V.SWAP

V.SWAP ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- )

Exchanges the contents of the vector specified by xvaddr1\sep1\d.#el with the contents of the vector specified by xvaddr2\sep2\d.#el.

Pronunciation: "v-swap"

##### V.TRANSFORM

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

xcfa specifies a unary operation that transforms one floating point number into another floating point number. V.TRANSFORM performs the unary operation indicated by xcfa on each of the elements in the source vector specified by xvaddr1\sep1\d.#el and stores the result in the destination vector specified by xvaddr2\sep2\d.#el. The source vector may equal the destination vector.

Pronunciation: "v-transform"
Attributes: S

##### V/

V/ ( xvaddr1\sep1\xvaddr2\sep2\xvaddr3\sep3\d.#el -- )

Divides each element of the source1 vector specified by xvaddr1\sep1\d.#el by the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el and places the result in the corresponding element of the destination vector specified by xvaddr3\sep3\d.#el. The destination vector may be one of the source vectors.

Pronunciation: "v-divide"
Attributes: S

##### V<

V< ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- flag )

flag is true if every element in the source1 vector specified by xvaddr1\sep1\d.#el is less than the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el.

Pronunciation: "v-less-than"

##### V>

V> ( xvaddr1\sep1\xvaddr2\sep2\d.#el -- flag )

flag is true if every element in the source1 vector specified by xvaddr1\sep1\d.#el is greater than the corresponding element in the source2 vector specified by xvaddr2\sep2\d.#el.

Pronunciation: "v-greater-than"

##### VALLOT

VALLOT ( n -- )

Reserves n bytes in the variable area by incrementing the variable pointer VP by n. An error occurs if the VALLOT operation causes VP 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: "v-allot"

##### VARIABLE

VARIABLE ( <name> -- )

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

VARIABLE <name>

Attributes: D

##### VC,

VC, ( byte -- )

Stores byte at the next available location in the variable area and increments the variable pointer VP by 1. An error occurs if byte is not correctly stored; e.g. if VP does not point to RAM. An error occurs if the VC, operation causes VP 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: "v-c-comma"

##### VFORTH

VFORTH ( -- xaddr )

A user variable that contains the xnfa (extended name field address) of the top word in the FORTH vocabulary, which is the default vocabulary to which the programmer's definitions are typically appended. In turnkeyed (autostarted) applications that require the interpreter to run in the final application, the autostart word should initialize VFORTH to contain the xnfa of the last word defined. For an example of use, see the definition of the application's autostart routine in the "Putting It All Together" chapter in the Software Manual.

Attributes: U

##### VHERE

VHERE ( -- xaddr )

Places on the stack the xaddr of the next available location in the variable area. Equivalent to VP X@.

Pronunciation: "v-here"
Attributes: U

##### VOCABULARY

VOCABULARY ( <name> -- )

Creates and initializes to LATEST a 32 bit xhandle in the variable area. When <name> executes, this xhandle is stored into the user variable CONTEXT so that the <name> vocabulary branch is searched first during dictionary searches.

Attributes: D

##### VP

VP ( -- xaddr )

User variable that contains the 32-bit Variable Pointer. The contents of VP are placed on the stack by VHERE and are modified by VALLOT. The command VP X@ is equivalent to VHERE; it yields the xaddr of the next available location in the variable area. The command VP @ is equivalent to VPAGE; it yields the page of the definitions area.

Pronunciation: "v-p"
Attributes: U

##### WARM

WARM ( -- )

Restarts the QED-Forth system and clears the data and return stacks and executes ABORT. Unlike COLD, WARM does not initialize all of the user variables to their default values.

Also see the "Program Development Techniques" chapter in the Software Manual for a detailed discussion of WARM and COLD restarts.

##### WHICH.MAP

WHICH.MAP ( -- [0] or [1] )

Returns a 0 if the current memory map is the "standard map", and returns a 1 if the current map is the "download map" on flash-carrying boards. If the standard map is active, pages 4, 5, and 6 are addressed in the S1 flash, and pages 1, 2, and 3 are addressed in the S2 RAM. If the download map is active, pages 4, 5, and 6 are addressed in the S2 RAM, and pages 1, 2, and 3 are addressed in the S1 flash memory. This routine allows a user or program to verify which map is currently being used. After a "factory cleanup" operation, the standard map is active.

##### WHILE

WHILE ( flag -- )

Used inside a colon definition to mark the beginning of the "while true" portion of a BEGIN … WHILE … REPEAT loop. If flag is TRUE, the loop continues and the words between WHILE and REPEAT are executed, after which control is transferred to the word following BEGIN. If flag is FALSE, the loop terminates and execution continues with the word following REPEAT. Use as:

BEGIN
words to be iteratively executed
flag WHILE    words to be iteratively executed
REPEAT

An error is issued if BEGIN WHILE and REPEAT are not properly paired inside a colon definition.

Attributes: C, I

##### WIDTH

WIDTH ( -- xaddr )

A user variable that contains the number of characters saved in a name entry by CREATE. Minimum value is 2, maximum is 31.

Attributes: U

##### WORD

WORD ( char1 -- xaddr | char1 is delimiter, xaddr = POCKET )

Parses the next word delimited by the specified char1 from the input stream. Moves the parsed word as a counted string to the buffer at POCKET in common memory, and places the xaddr of POCKET on the data stack. If the word has more than 31 characters, only the first 31 characters are moved and the count is clamped to 31. WORD appends a space to the counted string in POCKET; the space is not included in the string's count. If the input stream is exhausted when WORD executes, the count left at POCKET equals 0. If the specified delimiter char1 is a space, then leading spaces are ignored. If BLK = 0, the input stream is the terminal input buffer TIB. Otherwise WORD executes BLOCK so that the input stream is available in a block buffer. The value of >IN specifies the offset from the start of the input stream to the first character to be parsed. WORD leaves >IN pointing 1 byte past the terminating delimiter unless the input stream is exhausted, in which case >IN is left pointing 1 byte past the last valid location in the input stream. The interpreter executes BL WORD to parse input commands, and then calls (#FIND) to search for the parsed command in the dictionary. To parse strings longer than 31 characters, use PARSE.

Attributes: M

##### WORDS

WORDS ( -- )

Prints all words in the CURRENT vocabulary. WORDS incorporates PAUSE.ON.KEY, so the printout can be terminated by typing a carriage return or . (dot); it can be suspended and resumed by typing other characters, and it responds to XON/XOFF handshaking (see PAUSE.ON.KEY). Each word is printed left justified in a field of 16 or 32 characters, 3 names per line. Characters that are not saved in the headers are represented by the appropriate number of _ characters.

Attributes: M

##### X!

X! ( xaddr1\xaddr2 -- | xaddr1 is stored at xaddr2 )

Pronunciation: "x-store"

##### X.OVER.N

X.OVER.N ( xaddr\w -- xaddr\w\xaddr )

Copies the extended address located under the top data stack cell to the top of the data stack.

Pronunciation: "x-over-n"

##### X1-X2>D

X1-X2>D ( xaddr1\xaddr2 -- d )

Subtracts xaddr2 from xaddr1 to yield the signed double number result d. There is an unchecked error if one of the xaddresses is in common memory (addr ≥ 0x8000) and the other is in paged memory (addr ≤ 0x7FFF). Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "x-one-minus-x-two-to-d"

##### X1-X2>N

X1-X2>N ( xaddr1\xaddr2 -- n )

Subtracts xaddr2 from xaddr1 to yield the signed integer result n. There is an unchecked error if one of the xaddresses is in common memory (addr ≥ 0x8000) and the other is in paged memory (addr ≤ 0x7FFF), or if the difference can not be represented as a signed 16-bit integer. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "x-one-minus-x-two-to-n"

##### X2DROP

X2DROP ( xaddr1\xaddr2 -- )

Drops two extended addresses (4 cells) from the data stack.

Pronunciation: "x-two-drop"

##### X2DUP

X2DUP ( xaddr1\xaddr2 -- xaddr1\xaddr2\xaddr1\xaddr2 )

Duplicates the top two extended addresses on the data stack.

Pronunciation: "x-two-dupe"

##### X<>

X<> ( xaddr1\xaddr2 -- flag )

Flag is TRUE if the two extended addresses are not equal and FALSE otherwise.

Pronunciation: "x-not-equal"

##### X=

X= ( xaddr1\xaddr2 -- flag )

Flag is TRUE if the two extended addresses are equal and FALSE otherwise.

Pronunciation: "x-equals"

##### X>R

X>R ( xaddr -- )

Return Stack: ( R: – xaddr )

Transfers the top extended address on the data stack to the return stack.

Pronunciation: "x-to-r"
Attributes: C

##### X@

X@ ( xaddr1 -- xaddr2 )

Pronunciation: "x-fetch"

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

Adds a named member to the structure being defined and reserves room for a 32-bit extended 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.

Attributes: D

XADDR: ( <name> -- )

XADDR: is a synonym for DOUBLE:. It defines a 32-bit self-fetching variable called <name> which holds a 32-bit extended address.

Use as:

XADDR:  <name>

See also DOUBLE: Pronunciation: "x-address-colon"
Attributes: D

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

Adds a named member to the structure being defined and reserves room for u2 extended 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.

Attributes: D

##### XALIGN

XALIGN ( xaddr1 -- xaddr2 )

If xaddr1 is not an even multiple of 4 bytes, increases xaddr1 by 1, 2, or 3 bytes to yield xaddr2 which is an even multiple of 4 bytes. The vector and matrix operations require data structures to be 4-byte aligned; the heap manager and DIM.CONSTANT.MATRIX: and DIM.CONSTANT.ARRAY: use XALIGN to ensure that heap items, arrays, and matrices are 4-byte aligned.

Pronunciation: "x-align"

##### XCONSTANT

XCONSTANT ( xaddr <name> -- )

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

xaddr XCONSTANT <name>

Pronunciation: "x-constant"
Attributes: D

##### XD+

XD+ ( xaddr1\d -- xaddr2 )

Pronunciation: "x-d-plus"

##### XD-

XD- ( xaddr1\d -- xaddr2 )

Subtracts signed double number d from xaddr1 to yield xaddr2. Note that in paged memory, the address immediately preceding 0000 is address 0x7FFF on the preceding page.

Pronunciation: "x-d-minus"

##### XDROP

XDROP ( xaddr -- )

Drops an extended address (two cells) from the data stack.

Pronunciation: "x-drop"

##### XDUP

XDUP ( xaddr -- xaddr\xaddr )

Duplicates the top extended address (two cells) on the data stack.

Pronunciation: "x-dupe"

##### XDUP>R

XDUP>R ( xaddr -- xaddr )

Return Stack: ( R: – xaddr )

Copies the top extended address on the data stack to the return stack.

Pronunciation: "x-dup-to-r"
Attributes: C

##### XHNDL->

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

Adds a named member to the structure being defined and reserves room for a 32-bit extended handle 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: "x-handle"
Attributes: D

##### XIRQ.ID

XIRQ.ID ( -- n )

Returns the interrupt identity code for the external non-maskable interrupt called XIRQ. Used as an argument for ATTACH. The XIRQ interrupt is activated by an active-low signal on the XIRQ input pin and is enabled by the X bit in the condition code register.

Pronunciation: "x-i-r-q-i-d"

##### XMIT.DISABLE

XMIT.DISABLE ( -- xaddr )

A user variable that contains a flag that is set each time that EXPECT receives an XOFF character (ascii 19) and is cleared upon startup and each time EXPECT receives the XON character (ascii 17). XON and XOFF are standard handshaking characters used to control the flow of data between computers. The XMIT.DISABLE flag is not used by QED-Forth; it is provided in case the programmer needs to implement an XON/XOFF handshaking protocol. Note that inserting PAUSE.ON.KEY in the inner loop of a data dump word provides a very easy way to emulate XON/XOFF control of data dumps.

Pronunciation: "transmit-disable"
Attributes: U

##### XN+

XN+ ( xaddr1\n -- xaddr2 )

Pronunciation: "x-n-plus"

##### XN-

XN- ( xaddr1\n -- xaddr2 )

Subtracts signed integer n from xaddr1 to yield xaddr2. Note that in paged memory, the address immediately preceding 0000 is address 0x7FFF on the preceding page.

Pronunciation: "x-n-minus"

##### XOR

XOR ( w1\w2 -- w3 )

w3 is the result of a logical bit-by-bit exclusive-or of w1 and w2.

Pronunciation: "x-or"

##### XOVER

XOVER ( xaddr1\xaddr2 -- xaddr1\xaddr2\xaddr1 )

Places a copy of xaddr1 on top of the data stack.

Pronunciation: "x-over"

##### XPICK

XPICK ( xaddr\wn-1\...w1\w0\+n -- xaddr\wn-1\...\w1\w0\xaddr )

Copies to the top of the stack the extended address whose most significant cell is the +nth item on the stack (0-based, not including +n). An unchecked error occurs if there are fewer than +n+2 cells on the data stack or if +n is outside the range 0 to 255, inclusive. 0 XPICK is equivalent to XDUP, 1 XPICK is equivalent to X.OVER.N, 2 XPICK is equivalent to XOVER.

Pronunciation: "x-pick"

##### XR>

XR> ( -- xaddr )

Return Stack: ( R: xaddr – )

Transfers the top extended address on the return stack to the data stack.

Pronunciation: "x-r-from"
Attributes: C

##### XR>DROP

XR>DROP ( -- )

Return Stack: ( R: xaddr – )

Removes the top extended address from the return stack.

Pronunciation: "x-r-from-drop"
Attributes: C

##### XR@

XR@ ( -- xaddr )

Copies the top extended address on the return stack to the data stack.

Pronunciation: "x-r-fetch"
Attributes: C

##### XRANGE

XRANGE ( xaddr1\xaddr2\xaddr3 -- xaddr1\flag )

Flag is TRUE if xaddr1 is greater than or equal to xaddr2 and less than or equal to xaddr3. Otherwise flag is FALSE. There is an unchecked error if one or two of the xaddresses are in common memory (addr ≥ 0x8000) and other(s) are in paged memory (addr ≤ 0x7FFF). In other words, XRANGE works properly only if all three xaddresses are in paged memory, or if all three are in common memory. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "x-range"

##### XROT

XROT ( xaddr1\xaddr2\xaddr3 -- xaddr2\xaddr3\xaddr1 )

Rotates the top three extended addresses on the data stack.

Pronunciation: "x-rote"

##### XSWAP

XSWAP ( xaddr1\xaddr2 -- xaddr2\xaddr1 )

Exchanges the top two extended addresses on the data stack.

Pronunciation: "x-swap"

##### XU+

XU+ ( xaddr1\u -- xaddr2 )

Pronunciation: "x-u-plus"

##### XU-

XU- ( xaddr1\u -- xaddr2 )

Subtracts unsigned integer u from xaddr1 to yield xaddr2. Note that in paged memory, the address immediately preceding 0000 is address 0x7FFF on the preceding page.

Pronunciation: "x-u-minus"

##### XU<

XU< ( xaddr1\xaddr2 -- flag )

Flag is TRUE if xaddr1 is less than xaddr2. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "x-u-less-than"

##### XU>

XU> ( xaddr1\xaddr2 -- flag )

Flag is TRUE if xaddr1 is greater than xaddr2. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "x-u-greater-than"

##### XVARIABLE

XVARIABLE ( <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 to hold <name>'s contents. <name> is referred to as an "xvariable". Use as:

XVARIABLE <name>

Pronunciation: "x-variable"
Attributes: D

##### ZERO

ZERO ( -- r | r = 0.0 )

Puts the floating point representation for zero (= 0\0) on the data stack.

##### ZERO.ARRAY

ZERO.ARRAY ( array.xpfa -- )

Stores 0 into each byte of the specified array.

##### ZERO.MATRIX

ZERO.MATRIX ( matrix.xpfa -- )

Stores 0 into each byte of the specified matrix.

##### [

[ ( -- )

Sets STATE equal to 0 and enters the execution mode so that subsequent text from the input stream is executed.

Pronunciation: "left-bracket"
Attributes: I

##### [0]

[0] ( array.xpfa -- [xaddr] or [0\0] | xaddr is array base address )

Returns the base address (that is, the address of the first element) of the array or matrix indicated by array.xpfa. Returns 0\0 if the array or matrix is undimensioned. No error checking is performed.

Pronunciation: "bracket-zero"

##### [COMPILE]

[COMPILE] ( <word> -- )

Removes the next <name> from the input stream and compiles a call to <name> into the current definition. Use as:

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

where <namex> is typically not immediate and <name> is typically immediate. [COMPILE] forces the immediate word <name> to be compiled into the definition of <namex> instead if executing while <namex> is being defined. Consult the Advanced Topics chapter of the Software Manual for further description.

Pronunciation: "bracket-compile"
Attributes: C, I

##### []

[] ( n1...nn\array.xpfa -- xaddr | n1...nn = indices )

Returns the extended address xaddr of the element whose indices are n1…nn in the array specified by array.xpfa. If DEBUG is on, ABORTs if the indices are invalid. Typical use:

<indices> ' <array.name> []

Pronunciation: "brackets"

##### \

\ ( -- )

Ignores all remaining input on the current line. Very useful for inserting descriptive comments into QED-Forth source code.

Pronunciation: "back-slash"
Attributes: I

##### ]

] ( -- )

Sets STATE equal to -1 and enters the compilation mode so that subsequent text from the input stream is compiled instead of being executed.

Pronunciation: "right-bracket"
Attributes: I

##### |2!|

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

Stores two 16 bit integers at xaddr. Disables interrupts during the store to ensure that an interrupting routine or task will read valid data. w2 is stored at xaddr and w1 is stored at xaddr+2. Can also be used to store a double number at xaddr. Disables interrupts for 28 cycles (7 microseconds) unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 260 cycles. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "bar-two-store"

##### |2@|

|2@| ( xaddr -- w1\w2 )

Fetches two 16 bit integers from xaddr. Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process. w2 is taken from xaddr and w1 is from xaddr+2. Can also be used to fetch a double number from xaddr. Disables interrupts for 28 cycles (7 microseconds) unless the specified 4 bytes straddle a page boundary, in which case interrupts are disabled for approximately 260 cycles. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "bar-two-fetch"

##### |F!|

|F!| ( r\xaddr -- )

Stores a floating point number at xaddr. Disables interrupts during the store to ensure that an interrupting routine or task will read valid data. A synonym for |2!|.

Pronunciation: "bar-f-store"

##### |F@|

|F@| ( xaddr -- r )

Fetches a floating point number from xaddr. Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process. A synonym for |2@|.

Pronunciation: "bar-f-fetch"

##### |X!|

|X!| ( xaddr1\xaddr2 -- )

Pronunciation: "bar-x-store"

##### |X1-X2|>U

|X1-X2|>U ( xaddr1\xaddr2 -- n )

Subtracts xaddr2 from xaddr1 and takes the absolute value of the result to yield the unsigned integer difference u. There is an unchecked error if one of the xaddresses is in common memory (addr ≥ 0x8000) and the other is in paged memory (addr ≤ 0x7FFF). Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.

Pronunciation: "abs-of-x-one-minus-x-two-to-u"

##### |X@|

|X@| ( xaddr1 -- xaddr2 )`

Fetches an extended address xaddr2 from memory location xaddr1. Disables interrupts during the fetch to ensure that an interrupting routine or task does not modify the contents while the fetch is in process. A synonym for |2@|.

Pronunciation: "bar-x-fetch"

This page is about: Forth Firmware Library Glossary, QED-Forth Programming Language, QED-Forth Real-time Embedded Operating System – A glossary of the functions in the 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.