Forth v4.4 Function Glossary (P-Z-})

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

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

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

PAD ( -- xaddr | xaddr = start of scratchpad area )

Returns the xaddr of the start of the PAD scratchpad area. The 32 bytes below PAD are used for floating point and integer string/number conversion, and the area above PAD is available as scratchpad memory for the programmer (but note that the kernel routines ASK.NUMBER, ASK.FNUMBER, INPUT.STRING, and RECEIVE.HEX write text strings into the PAD). Equivalent to

UPAD X@

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

Attributes: U

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

Adds a named member to the structure being defined and reserves room for a 1-cell (16-bit) page 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: "page"
Attributes: D

PAGE.TO.FLASH ( page -- )

Transfers the 32 Kbyte contents of the specified RAM source_page to the parallel page in flash. If the current memory map is the "download map", then valid source pages are 4, 5, or 6, (and, if a 512K RAM is installed, pages 0x10-17). Page 4 RAM is transferred to page 1 flash, page 5 RAM is transferred to page 2 flash, page 6 RAM is transferred to page 3 flash, and pages in the range 0x10-17 are transferred to parallel flash pages in the range 0x18-1F. If the current memory map is the "standard map", then valid source pages are 1, 2, or 3 (and, if a 512K RAM is installed, pages 0x18-1F). Page 1 RAM is transferred to page 4 flash, page 2 RAM is transferred to page 5 flash, page 3 RAM is transferred to page 6 flash, and pages in the range 0x18-1F are transferred to parallel flash pages in the range 0x10-17. An "invalid input parameter" error is issued if an invalid source_page is specified. A "can't program flash" error is issued if the flash cannot be programmed. This function uses the RAM at addresses 0x3000-3FFF on page 0F and the 68HC11's on-chip RAM at hex B200 to B3CF to manage the write to the flash (the real-time clock and C/Forth interrupt stack reserve the bytes at B3D0 to B3FF). The remaining on-chip RAM at B000 to B1FF remains available to the user.

PAGE.TO.RAM ( page -- )

Transfers the 32 Kbyte contents of the specified flash source_page to the parallel page in RAM. If the current memory map is the "download map", then valid source pages are 1, 2, or 3 (and, if a 512K RAM is installed, pages 0x18-1F). Page 1 flash is transferred to page 4 RAM, page 2 flash is transferred to page 5 RAM, page 3 flash is transferred to page 6 RAM, and pages in the range 0x18-1F are transferred to parallel RAM pages in the range 0x10-17. If the current memory map is the "standard map", then valid source pages are 4, 5, or 6 (and, if a 512K RAM is installed, pages 0x10-17). Page 4 flash is transferred to page 1 RAM, page 5 flash is transferred to page 2 RAM, page 6 flash is transferred to page 3 RAM, and pages in the range 0x10-17 are transferred to parallel RAM pages in the range 0x18-1F. An "invalid input parameter" error is issued if an invalid source_page is specified.

PARITY ( -- xaddr )

A system variable that contains a flag set by the programmer to specify the behavior of the secondary serial port (serial2) supported by QED-Forth's software UART. If the contents of PARITY are TRUE, a parity bit is appended to each transmitted character and a parity bit is expected in each incoming character. The level of the transmitted parity bit is set by the system variable PARITY.OUT, and the value of the parity bit of the most recently received character is stored in the system variable PARITY.IN. PARITY is initialized to FALSE by INIT.SERIAL2 and USE.SERIAL2 and at each reset or restart.

PARITY.IN ( -- xaddr )

A system variable that holds the value of the parity bit of the character most recently received by the secondary serial port (serial2, supported by the software UART) if PARITY is true. If the incoming parity bit was high, PARITY.IN is set to 1; otherwise it is set to 0. The contents are available to the programmer if parity checking of incoming data is required; the software UART does not check for correct parity.

See also PARITY

PARITY.OUT ( -- xaddr )

A system variable that holds the value of the parity bit of the character to be sent next by the secondary serial port (serial2, supported by the software UART) if PARITY is true. If the contents of PARITY are TRUE and the least significant byte of PARITY.OUT is nonzero, then the parity bit of the next outgoing character is set to one. If the contents of PARITY are TRUE and the least significant byte of PARITY.OUT is zero, then the parity bit of the next outgoing character is set to zero. The value stored in PARITY.OUT is not modified by the serial2 routines, and the application program must perform any required parity calculations.

See also PARITY

PARSE ( char1 -- xaddr\cnt | char1 is the terminating delimiter )

Parses a string delimited by the specified char1 from the input stream, and returns the xaddr\cnt of the parsed string, where xaddr is the address of the first character and cnt is the number of characters in the parsed string (the string may cross a page boundary). Unlike WORD, which also parses strings from the input stream, PARSE does not move the parsed string to POCKET. Thus it is suitable for parsing strings longer than 31 bytes (see WORD). 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 PARSE executes BLOCK so that the input stream is available in a block buffer. The contents of >IN specify the offset from the start of the input stream to the first character to be parsed. PARSE 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.

See also WORD

Attributes: M

PAUSE ( -- )

Stacks the state of the current task and passes control to the next AWAKE task in the round-robin task list. You can embed calls to PAUSE in any task when you wish to give other tasks a chance to run. PAUSE may be used in multitasked systems whether or not the timeslicer is active. PAUSE switches tasks in (27 + 3.25n) microseconds, where n is the number of ASLEEP tasks encountered in the round robin task list. Of this time, interrupts are disabled for (20 + 3.25n) microseconds.

Attributes: M

PAUSE.ON.KEY ( -- )

Suspends execution of the calling word when a character is received and, with the exceptions noted below, resumes execution of the calling word when a second character is received. Typically coded into a loop structure to allow control of execution during debugging, or to control a data dump.

PAUSE.ON.KEY checks whether a character has been received. If no character has been received, it does nothing. If a character has been received and it is a carriage return, executes ABORT which clears the stacks and returns to the interpreter. If the character received is a . (dot) executes QUIT which returns to the interpreter without clearing the data stack. If any other character is received, suspends execution until another character other than carriage return or . is received. This word effectively responds to XON/XOFF from a host terminal; a QED-Forth word that dumps data and calls PAUSE.ON.KEY repeatedly will pause when the XOFF is received by QED-FORTH, and resume when XON is received. The word does not know that the characters are special; it just stops when receiving the first and resumes after the second. The kernel words DUMP, DUMP.INTEL, DUMP.S1, DUMP.S2, M.PARTIAL, M., M.., and WORDS call PAUSE.ON.KEY.

Attributes: M

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

First performs the operation of STACK.FRAME, reserving +n bytes of room on the data stack and leaving xaddr that points to the top (lowest in memory) reserved byte in the data stack frame. PF.STACK.FRAME then zeros the first 4 bytes (lowest in memory, nearest top of stack) of the allocated stack frame. PF.STACK.FRAME should be used when creating a temporary array or matrix parameter field within a definition (See ARRAY.PF and MATRIX.PF for examples of use.) The first 4 bytes of a parameter field contain an xhandle to the heap, and the xhandle should always be initialized to 0\0 before the array or matrix is dimensioned. PF.STACK.FRAME performs this initialization on the temporary stack-based parameter field. There is an unchecked error if +n is less than 4.

See also STACK.FRAME, ARRAY.PF, MATRIX.PF and FRAME.DROP
Pronunciation: "p-f-stack-frame"

PFA>NAME ( xpfa -- )

Prints the name of the word associated with the specified extended parameter field address xpfa. Useful for error diagnostics to print the name of an array, matrix or other data structure given its xpfa. The name is printed as ?NAME? if no name corresponding to xpfa is found in the dictionary.
Pronunciation: "p-f-a-to-name"
Attributes: M

PFA>NFA ( xpfa -- [xnfa] or [0\0] )

Given the extended parameter field address xpfa of a word in the dictionary, searches the dictionary and returns the extended name field address xnfa of the word. If the name associated with xpfa cannot be found in the dictionary, returns 0\0.

See also ' and NFA.FOR
Pronunciation: "p-f-a-to-n-f-a"

PI ( -- r )

Places the floating point value pi (= 3.1416) on the stack.

PI/2 ( -- r )

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

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

Copies the +nth item (not including n) to the top of the stack, where the top stack item is item#0, the next is item#1, etc. An unchecked error occurs if there are fewer than n+1 items on the data stack. 0 PICK is equivalent to DUP, 1 PICK is equivalent to OVER.

POCKET ( -- xaddr | xaddr is the start of the pocket buffer )

Returns the xaddress of the start of the POCKET buffer. POCKET is a 32-byte (minimum) scratch area used by WORD. Equivalent to

UPOCKET  @  DEFAULT.PAGE

FIND executes COLD if POCKET is not in the common RAM.

Attributes: U

PORTA ( -- xaddr )

Returns the extended address (0x8000\0) of the 8 bit PortA register in the 68HC11. This port is available to the user and is associated with various counting and timing functions. Note that the software UART that implements the secondary serial port uses bits 3 and 4 of PORTA, so care must be taken not to alter the direction or state of these bits if the secondary serial port is in use. PORTA can be accessed with the standard C@, C!, SET.BITS, CLEAR.BITS, TOGGLE.BITS, and CHANGE.BITS operators. It is recommended that the latter four uninterruptable operators be used to modify the available port bits if the secondary serial port is in use. The PORTA.DIRECTION register sets the data direction of the pins in PORTA.
Pronunciation: "port-A"

PORTA.DIRECTION ( -- xaddr )

Returns the extended address (0x8001\0) of the 8 bit DDRA register in the 68HC11 which sets the data direction of PORTA. To configure a PORTA pin to be an output, write a 1 to the corresponding bit position in PORTA.DIRECTION. Similarly, to configure a PORTA pin to be an input, write a 0 to the corresponding bit position in PORTA.DIRECTION. Note that the software UART that implements the secondary serial port uses bits 3 and 4 of PORTA, so care must be taken not to alter the direction or state of these bits if the secondary serial port is in use. The PORTA.DIRECTION register can be accessed with the standard C@, C!, SET.BITS, CLEAR.BITS, TOGGLE.BITS, and CHANGE.BITS operators.
Pronunciation: "port-A-direction"

PORTD ( -- xaddr )

Returns the extended address (0x8008\0) of the 8 bit PortD register in the 68HC11. This port implements the primary serial channel on bits 0 and 1, and the serial peripheral interface (SPI) on bits 2-5. If the SPI is not in use (which implies that the 12 bit A/D and 8 bit D/A are not in use) then bits 2, 3, 4, and 5 of PORTD are available as general purpose inputs and outputs. The data direction of these bits is set by register PORTD.DIRECTION. PORTD can be accessed with the standard C@, C!, SET.BITS, CLEAR.BITS, TOGGLE.BITS, and CHANGE.BITS operators.

See also INIT.SPI and SPI.OFF
Pronunciation: "port-D"

PORTD.DIRECTION ( -- xaddr )

Returns the extended address (0x8009\0) of the 8 bit DDRD register in the 68HC11 which sets the data direction of bits 2-5 of PORTD. PORTD implements the primary serial channel on bits 0 and 1, and the serial peripheral interface (SPI) on bits 2-5. If the SPI is not in use (which implies that the 12 bit A/D and 8 bit D/A are not in use) then bits 2, 3, 4, and 5 of PORTD are available as general purpose inputs and outputs. To configure a PORTD pin to be an output, write a 1 to the corresponding bit position in PORTD.DIRECTION. Similarly, to configure a PORTD pin to be an input, write a 0 to the corresponding bit position in PORTD.DIRECTION. This register can be accessed with the standard C@, C!, SET.BITS, CLEAR.BITS, TOGGLE.BITS, and CHANGE.BITS operators.

See also INIT.SPI and SPI.OFF
Pronunciation: "port-D-direction"

PORTE ( -- xaddr )

Returns the extended address (0x800A\0) of the 8 bit PortE register in the 68HC11. This port can either be used as an 8 channel 8 bit A/D converter, or as an octal digital input port. PORTE can be accessed with the standard C@ operator.

See also A/D8.ON and A/D8.OFF
Pronunciation: "port-E"

PREV ( -- xaddr )

A user variable containing the extended address of the most recently accessed block buffer.

Attributes: U

PRIORITY.AUTOSTART ( xcfa -- )

Compiles a 6-byte sequence at locations 0x7FFA-0x7FFF on page 4 so that upon subsequent restarts and ABORTs, the routine having the specified xcfa will be automatically executed. This allows a finished application to be automatically entered upon power up and resets. In contrast to the EEPROM-based AUTOSTART function, the PRIORITY.AUTOSTART vector is located in paged memory which is in flash memory in turnkeyed "production" boards. Thus PRIORITY.AUTOSTART facilitates the autostarting of flash-based systems. ABORT (which is called by the error handler and upon every reset or restart) checks the priority autostart vector first and executes the specified routine (if any). If no priority autostart routine is posted or if the specified routine terminates, ABORT then checks the EEPROM-based autostart vector (see AUTOSTART) and executes the specified routine (if any). If no autostart routine is posted or if the specified routine terminates, ABORT then invokes QUIT which is the QED-Forth interpreter. PRIORITY.AUTOSTART is Flash smart; it writes to page 4 whether page 4 addresses RAM or Flash at the time. In the standard map PRIORITY.AUTOSTART writes directly to Flash in page 4. In the download memory map it also writes to page 4, now RAM. Subsequently page 4 can be copied to Flash and the Flash readdressed onto page 4 in the standard map.

Implementation detail: At location 7FFAH on page 4, PRIORITY.AUTOSTART writes the pattern 1357 followed by the four byte xcfa; make sure that page 4 is not write protected when executing PRIORITY.AUTOSTART. To undo the effects of this command and return to the default startup action, make sure that page 4 is un-write-protected RAM and call NO.AUTOSTART (which clears both the priority autostart and the EEPROM-based autostart vectors). To recover from the installation of a buggy priority autostart routine if page 4 is RAM, make sure that page 4 is not write-protected and invoke use the special cleanup mode.

See also AUTOSTART

PULSE.EDGE.ID ( -- n )

Returns the interrupt identity code for the pulse accumulator input edge detector which is associated with port bit PA7. Used as an argument for ATTACH.
Pronunciation: "pulse-edge-i-d"

PULSE.OVERFLOW.ID ( -- n )

Returns the interrupt identity code for the pulse accumulator overflow detector which is associated with port bit PA7. Used as an argument for ATTACH.
Pronunciation: "pulse-overflow-i-d"

PUT.CURSOR ( n1\n2 -- | n1 = line#, n2 = character# )

Positions the LCD display cursor at the line number specified by n1 and the character number specified by n2. For all character and Hitachi graphics displays, the next character or graphical byte sent to the display by the CHAR>DISPLAY routine will appear at the specified cursor position, and then the cursor position will automatically increment. (Note that for Toshiba graphics displays, PUT.CURSOR affects only the cursor in text mode, and you must use IS.DISPLAY.ADDRESS to specify the location of the next graphical data byte.) n1 and n2 are 0 based (that is, the top line on the display is line#0, and the left-most character on each line is character#0). PUT.CURSOR clamps n1 to one less than LINES/DISPLAY, and clamps n2 to one less than CHARS/DISPLAY.LINE. 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#. Note that the cursor may not be visible, and is never visible in graphics mode (see DISPLAY.OPTIONS). Also note that after the cursor reaches the end of a line it may skip to the start of a line elsewhere on the display. Finally, consider using (UPDATE.DISPLAY) instead of UPDATE.DISPLAY to avoid re-homing the cursor after executing PUT.CURSOR. This routine intermittently disables interrupts for 28 cycles (7 microseconds) per command byte to implement clock stretching.

See also DISPLAY.OPTIONS

QUERY ( -- )

Executes

TIB CHARS/LINE @ EXPECT

to accept a line of up to CHARS/LINE characters from the serial port and store them in the terminal input buffer. Saves the number of characters actually received in the user variable #TIB. Sets >IN and BLK to 0 so that the next execution of WORD will parse the received line of input starting at the first character received. This is the main serial input word in the QED-Forth interpreter. Note that the terminal input buffer may be on any page, but may not cross a page boundary.

Attributes: M

QUIET ( -- xaddr )

A user variable that holds a flag that controls the word BEEP. BEEP is called when an error is detected. If the flag in QUIET is false, BEEP EMITs the bell character when executed to give an audible warning. If the flag is true, BEEP does nothing. BEEP is called by the system error routine, so QUIET controls whether system errors emit an audible beep.

Attributes: U

QUIT ( -- )

Enters execution mode and begins an infinite loop (terminated by errors) that repeatedly executes QUERY INTERPRET to read in a new line of input and interpret it. The return stack is cleared after each line of input is interpreted while in execution mode. This is the top level word in the QED-Forth interpreter. Consult the Software Manual for a detailed description of this word.

Attributes: M

R0 ( -- xaddr )

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

See also RP!
Pronunciation: "r-zero"
Attributes: U

R> ( -- w )

Return Stack: ( R: w – )

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

R>DROP ( -- )

Return Stack: ( R: w – )

Drops the top cell from the return stack.
Pronunciation: "r-from-drop"
Attributes: C

R@ ( -- w )

Return Stack: ( R: w – w )

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

RANDOM ( -- n )

Generates n, a pseudo-random 16-bit integer.

See also RANDOM#

RANDOM# ( -- xaddr )

A user variable that holds the last 16-bit number generated by RANDOM, or the 16-bit mantissa of the last floating point random number generated by FRANDOM. Storing a specific integer (a "seed") into RANDOM# leads to the generation of a reproducible series of pseudo-random numbers by repeated calls to FRANDOM or RANDOM. This may be useful for debugging words that use random numbers.
Pronunciation: "random-number"
Attributes: U

RANDOM.GAUSSIAN ( -- r )

r is a random number drawn from a Gaussian distribution with unity standard deviation and zero mean. Uses the Box-Muller method.

Attributes: S

RANDOMIZED ( matrix.xpfa -- )

Fills the specified matrix with random numbers drawn from a Gaussian distribution with 0 mean and unity standard deviation.

See also RANDOM.GAUSSIAN

Attributes: S

RANGE ( n1\n2\n3 -- n1\flag )

Flag is TRUE if n1 is greater than or equal to n2 and less than or equal to n3. Otherwise flag is FALSE.

See also URANGE

RANGE.OF ( n1\n2\n3 -- [n1] or [] )

Used inside a CASE … ENDCASE structure to mark the beginning of a conditional statement. If n2 ≤ n1 ≤ n3 then n1, n2, and n3 are dropped and execution continues with the words between RANGE.OF and ENDOF and then skips to the word after ENDCASE. Otherwise, n2 and n3 are dropped and execution continues after the next ENDOF. Use as:

n1 CASE
n2 n3 RANGE.OF  executed if n1 in range (n2,n3)    ENDOF
n4 n5 RANGE.OF  executed if n1 in range (n4,n5)    ENDOF
      words to be executed if not in range (n2,n3) or (n4,n5)
ENDCASE

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

See also OF
Pronunciation: "range-of"
Attributes: C, I

READ.ELAPSED.SECONDS ( -- u\ud | u = #msec, ud = #sec )

Returns the elapsed time on the timeslice clock since it was initialized to 0\0 by INIT.ELAPSED.TIME. ud is the number of elapsed seconds, and u is the number of milliseconds since the last integral second on the timeslice clock. The resolution equals the period of the timeslice clock (the default is 5 msec).

See also READ.ELAPSED.TIME, TIMESLICE.COUNT, START.TIMESLICER,and 100US=TIMESLICE.PERIOD

READ.ELAPSED.TIME ( -- u1\u2\u3\u4\u5 | u1 msec, u2 sec, u3 min, u4 hrs,u5 days )

Returns the number of milliseconds, seconds, minutes, hours, and days that the timeslice clock (supported by OC2) has run since it was initialized to 0\0 by INIT.ELAPSED.TIME. u5 is the number of days, u4 is the number of hours since the last integral day on the clock, u3 is the number of minutes since the last integral hour on the clock, u2 is the number of seconds since the last integral minute on the clock, and u1 is the number of milliseconds since the last integral second on the clock. The resolution equals the period of the timeslice clock (the default is 5 msec). The maximum time that the clock can represent is proportional to the timeslice period; the clock can represent times to over 248 days if the default 5 msec timeslice period is used.

See also READ.ELAPSED.TIME, TIMESLICE.COUNT, START.TIMESLICER, and *100US=TIMESLICE.PERIOD

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

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

Reads the battery-operated real-time clock (if present), returning 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

Due to a hardware limitation, the hundredths of second parameter always reads as 0; it is included in the stack picture to maintain backward compatibility with prior code. READ.WATCH uses the top 16 bytes of on-chip RAM at B3F0-B3FF as a scratchpad buffer. Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years.

See also SET.WATCH

READ/WRITE ( xaddr\n\flag -- | xaddr=buffer, n = block#, flag=true to read )

Calls the routine whose xcfa is stored in the user variable UREAD/WRITE. If flag is false, the routine specified by xcfa writes a 1 Kbyte block of data from the block buffer starting at xaddr to the mass memory block specified by n plus the contents of OFFSET. If flag is true, the routine specified by xcfa reads a 1 Kbyte block of data from the mass memory block specified by n + OFFSET to the block buffer starting at xaddr. The routine should trap all errors (invalid disk block, etc.) The default routine whose xcfa is stored in UREAD/WRITE implements a "ram disk" mass memory.

See also IS.RAMDISK and BLOCK.BUFFERS
Pronunciation: "read-slash-write"
Attributes: M, U

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

Adds a named member to the structure being defined and reserves room for a real (floating point) 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: "real"
Attributes: D

REAL: ( <name> -- )

REAL: is a synonym for DOUBLE:. REAL: defines a 32-bit self-fetching variable which holds a 32-bit floating point value (a real number). Use as:

REAL: <name>

Pronunciation: "real-colon"
Attributes: D

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

Adds a named member to the structure being defined and reserves room for u2 real (floating point) 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: "reals"
Attributes: D

RECEIVE ( xmailbox -- wd | wd is the received message )

If xmailbox is empty (i.e., if it contains 0\0), executes PAUSE until the mailbox contains a message. If xmailbox contains a message (i.e., if it does not contain 0\0), fetches the contents of xmailbox and stores a 0\0 into xmailbox to indicate that the message has been received and that the mailbox is now empty. To ensure that the state of the mailbox is correctly determined, RECEIVE disables interrupts for 26 to 61 cycles (6.5 to 15.25 microseconds).

See also SEND, ?RECEIVE and MAILBOX:

Attributes: M

RECEIVE.HEX ( xaddr1 <text> -- )

Accepts a download in standard Intel hex or Motorola S1 or S2 or S3 hex formats and initializes the memory locations starting at the specified xaddr1 accordingly. The first address specified in the <text> hex dump is stored in memory at xaddr1, and all subsequent bytes are stored in QED memory preserving the relative spacing of data specified in the <text> hex dump. If the specified xaddr1 is FFFF0XFFFF (that is, a 32-bit -1), the memory storage addresses are as specified in the hex dump itself. The QED paged memory is treated as a contiguous memory space; recall that the location following 7FFF on a given page is location 0000 on the following page. Accepts empty lines. If a format or checksum error is detected, emits an 'X' character to signal the error, but does not abort. Aborts with a "Missing delimiter" message if the first character on a line is not a : or S character. Terminates when an end-of-file record is received; the final line of an Intel hex dump is

:00000001FF

and the standard final line of a Motorola hex dump is

S9030000FC

although any S7, S8, or S9 termination record will terminate reception. Motorola S0 header records are accepted and ignored. Each input text line is temporarily stored at PAD. Be sure that the PAD buffer is large enough to accommodate a full line (decimal 80 bytes or more is safe). (See the glossary entries for DUMP.INTEL, DUMP.S1, and DUMP.S2 for descriptions of Intel and Motorola hex formats.)

Implementation detail: RECEIVE.HEX calculates an offset as the specified xaddr1 minus the first address specified in the <text> file. This offset is then added to every byte's file address (specified in the <text> file) to calculate the QED destination address. This scheme allows the data in a <text> hex dump file with arbitrary reported addresses to be loaded starting at any desired location in the QED memory space.
Pronunciation: "receive-hex"
Attributes: M

RECOVER.HANDLE ( xaddr -- [xhandle] or [0\0] )

Searches through the handle list for a handle that contains the specified base address xaddr. If found, returns the heap item's xhandle; otherwise, returns 0\0. Useful for debugging.

RECURSE ( -- )

Compiles into the current definition a call to the word currently being defined.

Attributes: C, I

REDEFINE ( xcfa1\xcfa2 -- | xcfa1 = operational word, xcfa2 = null word )

Resolves a forward reference or redefines a word by writing a call to xcfa1, the extended code field address of an operational word, into the code field specified by xcfa2. Up to 9 bytes are written into the code field of xcfa2.

To implement a forward reference (that is, to use a word before its action or operation has been defined), first define a null definition as:

: <null.definition.name>
   NO.OP ;

Then define words which call <null.definition.name> .

Then define the operational word as

: <operational.definition.name>
   words defining the operation   ;

Then execute

CFA.FOR <operational.definition.name>
CFA.FOR <null.definition.name>
REDEFINE

Now, all the words that were compiled with calls to <null.definition.name> will execute <operational.definition.name>. Of course, when REDEFINE is executed, xcfa2 must be in modifiable RAM.

REDEFINE may also be used during debugging. If xcfa2 is the code field address of a word that is found to be buggy, a bug-free version with code field address xcfa1 can be defined, and a REDEFINE command will cause all compiled calls to the buggy routine to execute the debugged version instead:

CFA.FOR <debugged.definition.name>
CFA.FOR <buggy.definition.name>
REDEFINE

Two requirements must be met: xcfa2 must be in modifiable RAM, and the code field of xcfa2 must be at least 9 bytes long so that the redefinition will not overwrite other words in the dictionary. There is no error checking. For another (though less efficient) way to implement forward references, use EVALUATE.

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

Re-writes the contents of the parameter field of the specified dimensioned matrix. Modifies the number of rows and columns in the parameter field to have the specified values without changing any data in the matrix. Thus the data in the matrix is effectively reconfigured into the new number of rows and columns. Error if the previous product of #rows times #columns is not equal to the product of the specified #rows times #cols.

REGISTER: ( addr <name> -- )

Typically used to define names for the HC11's hardware registers, REGISTER: removes the next <name> from the input stream and defines an XCONSTANT called <name> which when executed leaves the specified register address under a 0 (designating the default page) on the data stack. REGISTER: enforces a minimum WIDTH of 6 in the saved name to minimize non-unique names when defining registers. For example, to define a register address for the timer counter register named TCNT on the processor, execute

HEX 800E  REGISTER:   TCNT

Pronunciation: "register-colon"
Attributes: D

RELEASE ( xresource -- )

If the current task owns the resource variable referenced by xresource (i.e., if xresource contains the current task's xtask.id), releases the resource by storing 0\0 in xresource. Otherwise, does nothing; this prevents a task from RELEASEing a resource controlled by another task. Interrupts are not disabled and PAUSE is not executed.

See also GET and RESOURCE.VARIABLE:

RELEASE.AFTER.LINE ( -- n )

A constant which is the default value stored into the SERIAL.ACCESS user variable. If stored into the SERIAL.ACCESS user variable of a task that is running the QED-Forth interpreter, prevents the low level I/O words KEY EMIT and ?KEY from executing GET or RELEASE on the active serial resource variable. Rather, the interpreter (that is, QUIT) GETs the serial resource before each line is received and RELEASEs the serial resource after each line is interpreted. This virtually eliminates the overhead required to GET and RELEASE during downloads, and allows the interpreter to run at sustainable baud rates to 19200 baud. 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.

See also SERIAL.ACCESS, RELEASE.NEVER, and RELEASE.ALWAYS

RELEASE.ALWAYS ( -- n )

A constant. Returns a value that, when stored into the SERIAL.ACCESS user variable, causes the low level I/O words KEY EMIT and ?KEY to always RELEASE the serial resource variable after each I/O operation. This is useful if the task that has control over the serial line (for example, the task running the QED-Forth interpreter) wants to share access to the serial port.

See also SERIAL.ACCESS, RELEASE.NEVER, and RELEASE.AFTER.LINE

CAUTION: Depending on which terminal program you use, you may find that storing RELEASE.ALWAYS into the QED-Forth task's SERIAL.ACCESS variable decreases the sustainable download baud rate to 9600 baud. To assure the highest sustainable download baud rate, it is recommended that RELEASE.AFTER.LINE be stored in the QED-Forth task's SERIAL.ACCESS variable during program development.

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.

RELEASE.NEVER ( -- n )

A constant. Returns a value that, when stored into the SERIAL.ACCESS user variable, prevents the low level I/O words KEY EMIT and ?KEY from executing the command SERIAL RELEASE. This is useful if the task that has control over the serial line (for example, the task running the QED-Forth interpreter) does not want to share access to the serial port.

See also SERIAL.ACCESS, RELEASE.ALWAYS, and RELEASE.AFTER.LINE

CAUTION: Depending on which terminal program you use, you may find that storing RELEASE.NEVER into the QED-Forth task's SERIAL.ACCESS variable decreases the sustainable download baud rate to 9600 baud. To assure the highest sustainable download baud rate, it is recommended that RELEASE.AFTER.LINE be stored in the QED-Forth task's SERIAL.ACCESS variable during program development.

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.

REPEAT ( -- )

Used inside a colon definition to mark the end of a BEGIN … WHILE … REPEAT loop structure. Use as:

BEGIN    ...
flag WHILE    ...
REPEAT

See BEGIN and WHILE.

Attributes: C, I

RESERVED ( u1\u2 -- u3 )

Used during definition of a structure to reserve an unnamed space equal to u2 bytes within the structure. 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.

Attributes: D

RESIZE.HANDLE ( xhandle\d -- flag )

Attempts to resize the heap item associated with xhandle so that it has a new size of d bytes. Retains as much data as possible in the heap item. The heap must have enough space to copy the heap item to be successful. A true flag is returned if the heap item is successfully resized. A false flag indicates failure (due to an invalid xhandle or inadequate heap space) and the original heap item is left unchanged.

RESOURCE.VARIABLE: ( <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 the resource variable's contents. <name> is referred to as a "resource variable". Use as:

RESOURCE.VARIABLE: <name>

Resource variables are used in multitasked systems to control access to shared resources (for example, an A/D converter, serial port, block of memory, etc.) When the resource associated with <name> is available, <name> contains 0\0. When it is controlled by a task (and hence unavailable to other tasks), it contains the task id of the controlling task. Before its first use, the resource variable must be initialized to 0\0. After initialization to 0\0, the only operators that should access the resource variable are GET ?GET and RELEASE. The following resource variables are pre-defined in the QED-Forth kernel:

DISK.RESOURCE      SPI.RESOURCE
SERIAL1.RESOURCE      SERIAL2.RESOURCE
A/D8.RESOURCE

Consult their glossary entries and the Software Manual for further descriptions and examples of use.

Attributes: D

RESTORE ( -- )

Restores the memory map user variables stored by the last execution of SAVE to their respective user variables.

See also SAVE

RIGHT.PLACES ( -- xaddr )

A user variable that holds the number of digits to be displayed to the right of the decimal point when a floating point number is printed in FIXED format.

See also F>FIXED$

Attributes: U

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

d is the number of bytes available in the HEAP.

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

Rotates the top three stack cells.
Pronunciation: "rote"

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.

See also COL→ V
Pronunciation: "row-to-v"

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

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

See also INIT.RS485 and RS485.TRANSMIT.
Pronunciation: "R-S-four-eighty-five-receive"

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

See also INIT.RS485 and RS485.RECIEVE.
Pronunciation: "R-S-four-eighty-five-transmit"

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 ( 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 ( 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 ( 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* ( 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+ ( 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- ( 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/ ( 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< ( 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> ( 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* ( 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+ ( 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- ( 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= ( 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= ( 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/ ( 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< ( 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> ( 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 ( 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 ( -- 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.

See also SP!
Pronunciation: "s-zero"
Attributes: U

S>D ( n -- d )

Sign-extends a single precision integer to a double precision equivalent.
Pronunciation: "s-to-d"

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.

See also (EEC!)

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

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

See also F>SCIENTIFIC$

SCIENTIFIC. ( r -- )

Prints r using SCIENTIFIC format.

See also F>SCIENTIFIC$
Pronunciation: "scientific-dot"
Attributes: M, S

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.

See also LIST
Pronunciation: "s-c-r"
Attributes: U

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

See also ?SEND, RECEIVE, ?RECEIVE, and MAILBOX:

Attributes: M

SERIAL ( -- xresource )

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

See also SERIAL1.RESOURCE

SERIAL.ACCESS ( -- xaddr )

A user variable containing a flag that controls when a task GETs and RELEASEs access to the serial resource. If more than one task needs access to the serial I/O port, this flag can help specify which task (if any) gets priority use. If SERIAL.ACCESS contains the value RELEASE.ALWAYS, then each I/O operation by KEY EMIT or ?KEY GETs the active serial resource before each I/O operation and RELEASEs the active serial resource after each character I/O operation is complete. If SERIAL.ACCESS contains the value RELEASE.NEVER, then I/O operations called by the task always GET but never RELEASE the serial resource variable. If SERIAL.ACCESS contains the value RELEASE.AFTER.LINE, then KEY EMIT and ?KEY never GET or RELEASE the serial resource. Rather, the QED-Forth interpreter (that is, QUIT) GETs the serial resource before each line is received and RELEASEs the serial resource after each line is interpreted. This virtually eliminates the overhead required to GET and RELEASE during downloads, and allows the interpreter to run at sustainable baud rates to 19200 baud. The default value stored in SERIAL.ACCESS after a COLD restart is RELEASE.AFTER.LINE.

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.

See also SERIAL1.RESOURCE, SERIAL2.RESOURCE, GET, RELEASE, KEY, EMIT, ?KEY, and QUIT.

Attributes: U

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.

See also USE.SERIAL1 and SERIAL2.AT.STARTUP
Pronunciation: "serial-one-at-startup"

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.

See also RESOURCE.VARIABLE:
Pronunciation: "serial-one-resource"

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

See also RESOURCE.VARIABLE:
Pronunciation: "serial-two-resource"

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.

See also (SET.BITS) and CLEAR.BITS

SET.BOOT.VECTOR ( xcfa -- )

Compiles a 6-byte sequence at locations 0x7FFA-0x7FFF on page 0x0C so that upon subsequent restarts and ABORTs, the function having the specified xcfa (execution address) will be executed BEFORE any other autostart routines are executed. The execution order at startup is: boot_vector, then priority_autostart, then autostart. Note that the page C write protect jumper must be removed for this function to be effective. The boot vector is most useful for extending the kernel in a "bullet-proof" way that cannot be overwritten unless the page C write protect jumper is removed. For example, suppose that you want to allow fail-safe field firmware upgrades using Compact Flash (CF) cards via Mosaic's CF Wildcard. This can be accomplished by removing the page C hardware write protect jumper, loading the CF Wildcard kernel extension on page 0x0C, and compiling a startup function on page C that checks for the presence of an "AUTOEXEC.QED" file that will be automatically executed (loaded) if present. Using Set.Boot.Vector, the startup function can be declared as a boot vector, and then the page C write protect jumper can be installed. The boot vector will be able check for the presence of a firmware upgrade file, and the hardware write protection of page C prevents the erasure of the boot vector or its code. To remove the boot vector, take off the page C write protect jumper and call CLEAR.BOOT.VECTOR, or perform a factory cleanup.

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

Due to a hardware limitation, the hundredths of second parameter is ignored; it is included in the stack picture to maintain backward compatibility with prior code. SET.WATCH uses the top 16 bytes of on-chip RAM at B3F0-B3FF as a scratchpad buffer. Once correctly set, the watch handles the differing numbers of days in each month, and correctly handles leap years.

See also READ.WATCH

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

See also BREAK

Attributes: U

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

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 ( coefficient.matrix.xpfa\residue.matrix.xpfa\solution.matrix.xpfa -- )

Solves a set of simultaneous linear equations. For example, 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! ( [...] -- )

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

Emits one space character. Equivalent to BL EMIT

Attributes: M

SPACES ( +byte -- )

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

Attributes: M

SPAN ( -- xaddr )

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

Attributes: U

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. Consult the high level source file steppers.4th in the Demos_and_Drivers directory of the distribution.

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.

See also INIT.SPI, SPI.ON, and SPI.OFF
Pronunciation: "s-p-i-i-d"

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.

See also INIT.SPI
Pronunciation: "init-S-P-I"

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.

See also RESOURCE.VARIABLE:
Pronunciation: "S-P-I-resource"

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

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, consult the glossary entry for DOWNLOAD.MAP. Note that the standard map is active after a "factory cleanup" operation.

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

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 ( -- 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 ( -- xaddr | xaddr is also the task's xtask.id )

A user variable that contains the status of a task. Typically contains one of the 16-bit constants AWAKE or ASLEEP. An ASLEEP task does not run as the multitasking executive goes around the round robin task list. STATUS is the first user variable in the user area, so the extended address returned by executing STATUS is also the base address of the user area. This base address is also referred to as the "task identifier" or "task id"; it is the address in common memory used to identify a particular task.

See also (STATUS)

Attributes: U

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

Stops the multitasker's timeslice clock by disabling the local OC2 timer interrupt mask. Cooperative (PAUSE-invoked) task switching is not affected. 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.

See also START.TIMESLICER

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-> ( 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-> ( 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: ( <name> -- xpfa\0 )

Begins a structure definition and creates a named constant <name> which, when executed, returns the size of the structure in bytes. Consult 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 ( 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:.

See also STRUCTURE.BEGIN:

Attributes: D

SWAP ( w1\w2 -- w2\w1 )

Exchanges the top two stack cells.

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

Returns the interrupt identity code for the software interrupt (SWI). Used as an argument for ATTACH. Read the SWI instruction in the assembler glossary.
Pronunciation: "s-w-i-i-d"

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.

See also EXPECT
Pronunciation: "tab-width"
Attributes: U

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

Converts the xaddress of a specified user variable xaddr1 in the current task to the xaddress of the equivalent user variable xaddr2 in the task specified by xtask.id. Facilitates the modification of user variables in other tasks. Use with care. For example, to put a task named OTHER.TASK asleep, execute

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

Pronunciation: "task's-user-variable"

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.

See also STATUS

Attributes: D

TEN ( -- r )

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

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.

See also IF and ELSE

Attributes: C, I

THIS.PAGE ( -- byte )

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

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.

See also QUERY

Attributes: U

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

See READ.ELAPSED.SECONDS and READ.ELAPSED.TIME.

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 ( xaddr1\xaddr2\u -- success_flag | xaddr1=src, xaddr2=dest, u = byte count )

Transfers the unsigned integer number of bytes, u (0 ≤ num ≤ 65,535), starting at the specified source extended address, xaddr1, to the specified destination extended address, xaddr2, 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.

TO.FLASH returns a flag equal to -1 if the programming was successful, or 0 if the programming failed. The most common reason for failure is a destination that is not in a programmable page in flash memory. Less likely, but possible, 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 512 Kbyte flash is present on the board, writable flash pages include pages hex 4, 5, 6, 7, 0xC, 0xD, and 0x10-17 in the standard map, and pages 1, 2, 3, 0xC, 0xD, and 0x18-1F in 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. Page 0x0C can be optionally write protected with a jumper, enabling the installation of bullet-proof kernel extensions that cannot be erased until the jumper is removed.

This function uses the RAM at addresses 0x3000-3FFF on page 0F and the 68HC11's on-chip RAM at hex B200 to B3CF to manage the write to the flash (the real-time clock and C/Forth interrupt stack reserve the bytes at B3D0 to B3FF). The remaining on-chip RAM at B000 to B1FF remains available to the user.

Caution: TO.FLASH is usually used at compile time to load code and data into Flash, but you may use it at runtime with the understanding that the prolonged disabling of interrupts by TO.FLASH can adversely affect real-time servicing of interrupts including those associated with the secondary serial line.

Upgrade notice: Kernel v4.41 upgrades TO.FLASH to accommodate newly available Flash devices. The various chips now require the following buffer sizes/location:

While it would be possible to use any of these chips, the kernel V4.41 product starting in 2014 ships with a 39SF040 flash chip, which is programmed using the 4 kbyte buffer at 0x3000-3FFF on page 0F.

See also PAGE.TO.FLASH

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

See also (TOGGLE.BITS)

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

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

Attributes: U

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 ( 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, use DUP.HEAP.ITEM.

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 ( -- 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 ( 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 ( -- flag | flag = -1 )

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

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

See also COUNT.TYPE

Attributes: M

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

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

See also TYPE.OF: and OR.TYPE.OF:

Attributes: D

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
      ADDR->   +HNDL.ADDR
   TYPE.END
      ADDR->   +END.HEAP
STRUCTURE.END

Pronunciation: "type-of"
Attributes: D

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 .

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

U. ( u -- )

Prints unsigned integer u with no leading spaces and 1 trailing space.
Pronunciation: "u-dot"
Attributes: M, S

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

See also /
Pronunciation: "u-slash"

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.

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

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

Divides the unsigned number u1 by 2 giving u2.

See also 2/
Pronunciation: "u-two-slash"

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

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

See also ?KEY
Pronunciation: "u-question-key"
Attributes: U

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

See also (ABORT) and CUSTOM.ABORT.
Pronunciation: "u-abort"
Attributes: U

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\+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.

See also D.R
Pronunciation: "u-d-dot-r"
Attributes: M, S

UEMIT ( -- xaddr )

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

See also EMIT
Pronunciation: "u-emit"
Attributes: U

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

See also DFIXX

Attributes: S

UFLOT ( u -- r )

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

See also DFLOT and FLOT
Pronunciation: "u-float"
Attributes: S

UKEY ( -- xaddr )

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

See also KEY
Pronunciation: "u-key"
Attributes: U

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* ( 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 ( 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 ( u1\u2 -- [u1] or [u2] )

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

See also MAX
Pronunciation: "u-max"

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

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

See also MIN
Pronunciation: "u-min"

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.

See also MOD
Pronunciation: "u-mod"

UNDERFLOW ( -- )

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

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

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

See also PAD
Pronunciation: "u-pad"
Attributes: U

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

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.

See also (UPDATE.DISPLAY) and 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 ( -- 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 ( 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 ( 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.

See also RANGE
Pronunciation: "u-range"

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.

See also CASE, OF, RANGE.OF
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.

See also READ/WRITE
Pronunciation: "u-read-slash-write"
Attributes: U

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

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

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.

See also BAUD2
Pronunciation: "use-serial-two"

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 ( -- 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* ( 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*+ ( 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+ ( 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, ( 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- ( 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= ( 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= ( 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 ( 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 ( r\xvaddr\sep\d.#el -- )

Stores r into each element of the vector specified by xvaddr\sep\d.#el.
Pronunciation: "v-fill"

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 ( 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 ( 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 ( 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 ( 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 ( 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/ ( 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< ( 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> ( 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 ( 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 ( <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, ( 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 ( -- 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, consult the definition of the application's autostart routine in the "Putting It All Together" chapter in the Software Manual.

See also LATEST, CONTEXT, CURRENT, FIND, and NFA.FOR

Attributes: U

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

See also FIND

Attributes: D

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

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. Consult the "Program Development Techniques" chapter in the Software Manual for a detailed discussion of WARM and COLD restarts.

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 flash, and pages 1, 2, and 3 are addressed in RAM. If the download map is active, pages 4, 5, and 6 are addressed in RAM, and pages 1, 2, and 3 are addressed in 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.

See also STANDARD.MAP and DOWNLOAD.MAP

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

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! ( xaddr1\xaddr2 -- | xaddr1 is stored at xaddr2 )

Stores the extended address xaddr1 at xaddr2. A synonym for 2!.
Pronunciation: "x-store"

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 ( 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 ( 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 ( xaddr1\xaddr2 -- )

Drops two extended addresses (4 cells) from the data stack.
Pronunciation: "x-two-drop"

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

Duplicates the top two extended addresses on the data stack.
Pronunciation: "x-two-dupe"

X<> ( xaddr1\xaddr2 -- flag )

Flag is TRUE if the two extended addresses are not equal and FALSE otherwise.
Pronunciation: "x-not-equal"

X= ( xaddr1\xaddr2 -- flag )

Flag is TRUE if the two extended addresses are equal and FALSE otherwise.
Pronunciation: "x-equals"

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

Fetches an extended address xaddr2 from memory location xaddr1. A synonym for 2@.
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.
Pronunciation: "x-address"
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 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.
Pronunciation: "x-addresses"
Attributes: D

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 ( 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+ ( xaddr1\d -- xaddr2 )

Adds signed double number d to xaddr1 to yield xaddr2. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "x-d-plus"

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

Drops an extended address (two cells) from the data stack.
Pronunciation: "x-drop"

XDUP ( xaddr -- xaddr\xaddr )

Duplicates the top extended address (two cells) on the data stack.
Pronunciation: "x-dupe"

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

See also EXPECT and PAUSE.ON.KEY
Pronunciation: "transmit-disable"
Attributes: U

XN+ ( xaddr1\n -- xaddr2 )

Adds signed integer n to xaddr1 to yield xaddr2. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "x-n-plus"

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 ( w1\w2 -- w3 )

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

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

Places a copy of xaddr1 on top of the data stack.
Pronunciation: "x-over"

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

Return Stack: ( R: xaddr – )

Removes the top extended address from the return stack.
Pronunciation: "x-r-from-drop"
Attributes: C

XR@ ( -- xaddr )

Return Stack: ( R: xaddr – xaddr )

Copies the top extended address on the return stack to the data stack.
Pronunciation: "x-r-fetch"
Attributes: C

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 ( xaddr1\xaddr2\xaddr3 -- xaddr2\xaddr3\xaddr1 )

Rotates the top three extended addresses on the data stack.
Pronunciation: "x-rote"

XSWAP ( xaddr1\xaddr2 -- xaddr2\xaddr1 )

Exchanges the top two extended addresses on the data stack.
Pronunciation: "x-swap"

XU+ ( xaddr1\u -- xaddr2 )

Adds unsigned integer u to xaddr1 to yield xaddr2. Note that in paged memory, the address immediately following 0x7FFF is address 0000 on the following page.
Pronunciation: "x-u-plus"

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< ( 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> ( 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 ( <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 ( -- r | r = 0.0 )

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

ZERO.ARRAY ( array.xpfa -- )

Stores 0 into each byte of the specified array.

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.

See also ] and STATE
Pronunciation: "left-bracket"
Attributes: I

[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] ( <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.

See also COMPILE
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.

See also (
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.

See also [ and STATE
Pronunciation: "right-bracket"
Attributes: I

|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@| ( 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!| ( 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@| ( 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!| ( xaddr1\xaddr2 -- )

Stores the extended address xaddr1 at xaddr2. Disables interrupts to ensure that an interrupting routine or task will read valid contents. A synonym for |2!|.
Pronunciation: "bar-x-store"

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