Chapter 4 Using Forth Tools

This chapter introduces the Forth programming language as it is implemented in OpenBoot. Even if you are familiar with Forth, work through the examples shown in this chapter; they provide specific, OpenBoot-related information.

The version of Forth contained in OpenBoot is based on ANS Forth. Appendix I, Forth Word Reference ," lists the complete set of available commands.

---

Note -

This chapter assumes that you know how to enter and leave the User Interface. At the ok prompt, if you type commands that hang the system and you cannot recover using a key sequence, you may need to perform a power cycle to return the system to normal operation.

---

Forth Commands

Forth has a very simple command structure. Forth commands, also called Forth words, consist of any combination of characters that can be printed. For example, letters, digits, or punctuation marks. Examples of legitimate words are shown below:

---

@
dump
.
0<
+
probe-scsi

---

Forth words must be separated from one another by one or more spaces (blanks). Characters that are normally treated as "punctuation" in some other programming languages do not separate Forth words. In fact, many of those "punctuation" characters are Forth words!

Pressing Return at the end of any command line executes the typed commands. (In all the examples shown, a Return at the end of the line is assumed.)

A command line can have more than one word. Multiple words on a line are executed one at a time, from left to right, in the order in which they were typed. For example:

---

ok testa testb testc
ok 

---

is equivalent to:

---

ok testa
ok testb
ok testc
ok 

---

In OpenBoot, uppercase and lowercase letters are equivalent in Forth word names. Therefore, testa, TESTA, and TesTa all invoke the same command. However, words are conventionally written in lowercase.

Some commands generate large amounts of output (for example, dump or words). You can interrupt such a command by pressing any key except q. (If you press q, the output is aborted, not suspended.) Once a command is interrupted, output is suspended and the following message appears:

---

More [<space>,<cr>,q] ? 

---

Press the space bar (<space>) to continue, press Return (<cr>) to output one more line and pause again, or type q to abort the command. When a command generates more than one page of output, the system automatically displays this prompt at the end of each page.

Data Types

The terms shown in Table 4-1 describe the data types used by Forth.

Table 4-1 Forth Data Type Definitions

Notation	Description
byte	An 8-bit value.
cell	The implementation-defined fixed size of a cell is specified in address units and the corresponding number of bits. Data-stack elements, return-stack elements, addresses, execution tokens, flags and integers are one cell wide. On OpenBoot systems, a cell consists of at least 32-bits, and is sufficiently large to contain a virtual address. The cell size may vary between implementations. A 32-bit implementation has a cell size of 4. A 64-bit implementation has a cell size of 8. OpenBoot 3.x is a 64-bit implementation.
doublet	A 16-bit value.
octlet	A 64-bit value; only defined on 64-bit implementations,
quadlet	A 32-bit value.

Using Numbers

Enter a number by typing its value, for example, 55 or -123. Forth accepts only integers (whole numbers); it does not understand fractional values (e.g., 2/3). A period at the end of a number signifies a double number. Periods or commas embedded in a number are ignored, so 5.77 is understood as 577. By convention, such punctuation usually appears every four digits. Use one or more spaces to separate a number from a word or from another number.

Unless otherwise specified, OpenBoot performs integer arithmetic on data items that are one cell in size, and creates results that are one cell in size.

Although OpenBoot implementations are encouraged to use base 16 (hexadecimal) by default, they are not required to do so. Consequently, you must establish a specific number base if your code depends on a given base for proper operation. You can change the number base with the commands decimal and hex to cause all subsequent numeric input and output to be performed in base 10 or 16, respectively.

For example, to operate in decimal, type:

---

ok decimal 
ok 

---

To change to hexadecimal, type:

---

ok hex
ok 

---

To identify the current number base, you can use:

---

ok 10 .d
16
ok 

---

The 16 on the display shows that you are operating in hexadecimal. If 10 showed on the display, it would mean that you are in decimal base. The .d command displays a number in base 10, regardless of the current number base.

The Stack

The Forth stack is a last-in, first-out buffer used for temporarily holding numeric information. Think of it as a stack of books: the last one you put on the top of the stack is the first one you take off. Understanding the stack is essential to using Forth.

To put a number on the stack, simply type its value.

---

ok 44  (The
value 44 is now on top of the stack)
ok 7 (The value
7 is now on top, with 44 just underneath)
ok 

---

Displaying Stack Contents

The contents of the stack are normally invisible. However, properly visualizing the current stack contents is important for achieving the desired result. To show the stack contents with every ok prompt, type:

---

ok showstack
44 7 ok 8
44 7 8ok noshowstack
ok 

---

The topmost stack item is always shown as the last item in the list, immediately before the ok prompt. In the above example, the topmost stack item is 8.

If showstack has been previously executed, noshowstack will remove the stack display prior to each prompt.

---

Note -

In some of the examples in this chapter, showstack is enabled. In those examples, each ok prompt is immediately preceded by a display of the current contents of the stack. The examples work the same if showstack is not enabled, except that the stack contents are not displayed.

---

Nearly all words that require numeric parameters fetch those parameters from the top of the stack. Any values returned are generally left on top of the stack, where they can be viewed or consumed by another command. For example, the Forth word + removes two numbers from the stack, adds them together, and leaves the result on the stack. In the example below, all arithmetic is in hexadecimal.

---

44 7 8 ok +
44 f ok +
53 ok 

---

Once the two values are added together, the result is put onto the top of the stack. The Forth word . removes the top stack item and displays that value on the screen. For example:

---

53 ok 12
53 12 ok .
12
53 ok .
53
ok   (The stack is now empty)
ok 3 5 + .
8
ok   (The stack is now empty) 
ok . 
Stack Underflow 
ok 

---

The Stack Diagram

To aid understanding, conventional coding style requires that a stack diagram of the form ( -- ) appear on the first line of every definition of a Forth word. The stack diagram specifies what the execution of the word does to the stack.

Entries to the left of -- represent those stack items that the word removes from the stack and uses during its operation. The right-most of these items is on top of the stack, with any preceding items beneath it. In other words, arguments are pushed onto the stack in left to right order, leaving the most recent one (the right-most one in the diagram) on the top.

Entries to the right of -- represent those stack items that the word leaves on the stack after it finishes execution. Again, the right-most item is on top of the stack, with any preceding items beneath it.

For example, a stack diagram for the word + is:

( nu1 nu2 -- sum )

Therefore, + removes two numbers (nu1 and nu2) from the stack and leaves their sum (sum) on the stack. As a second example, a stack diagram for the word. is:

( nu -- )

The word . removes the number on the top of the stack (nu) and displays it.

Words that have no effect on the contents of the stack (such as showstack or decimal), have a ( -- ) stack diagram.

Occasionally, a word will require another word or other text immediately following it on the command line. The word see, used in the form:

see thisword

is such an example.

Stack items are generally written using descriptive names to help clarify correct usage. See Table 4-2 for stack item abbreviations used in this manual.

Table 4-2 Stack Item Notation

Notation	Description
|	Alternate stack results shown with space, e.g. ( input -- addr len false | result true ).
???	Unknown stack item(s).
...	Unknown stack item(s). If used on both sides of a stack comment, means the same stack items are present on both sides.
< > <space>	Space delimiter. Leading spaces are ignored.
a-addr	Variable-aligned address.
addr	Memory address (generally a virtual address).
addr len	Address and length for memory region
byte bxxx	8-bit value (low order byte in a cell).
char	7-bit value (low order byte in a cell, high bit of low order byte unspecified).
cnt	Count.
len	Length.
size	Count or length.
dxxx	Double (extended-precision) numbers. 2 cells, most significant cell on top of stack.
<eol>	End-of-line delimiter.
false	0 (false flag).
n n1 n2 n3	Normal signed, one-cell values.
nu nu1	Signed or unsigned one-cell values.
<nothing>	Zero stack items.
o o1 o2 oct1 oct2	Octlet (64 bit signed value).
oaddr	Octlet (64-bit ) aligned address.
octlet	An eight-byte quantity.
phys	Physical address (actual hardware address).
phys.lo phys.hi	Lower / upper cell of physical address.
pstr	Packed string.
quad qxxx	Quadlet (32-bit value, low order four bytes in a cell).
qaddr	Quadlet (32-bit) aligned address.
true	-1 (true flag).
uxxx	Unsigned positive, one-cell values.
virt	Virtual address (address used by software).
waddr	Doublet (16-bit) aligned address.
word wxxx	Doublet (16-bit value, low order two bytes in a cell).
x x1	Arbitrary, one cell stack item.
x.lo x.hi	Low/high significant bits of a data item.
xt	Execution token.
xxx?	Flag. Name indicates usage (e.g. done? ok? error?).
xyz-str xyz-len	Address and length for unpacked string.
xyz-sys	Control-flow stack items, implementation-dependent.
( C: -- )	Compilation stack diagram.
( -- )( E: -- )	Execution stack diagram.
( R: -- )	Return stack diagram.

Manipulating the Stack

Stack manipulation commands (described in Table 4-3) allow you to add, delete, and reorder items on the stack.

Table 4-3 Stack Manipulation Commands

Command	Stack Diagram	Description
clear	( ??? -- )	Empty the stack.
depth	( ... -- ... u )	Return the number of items on the stack.
drop	( x -- )	Remove top item from the stack.
2drop	( x1 x2 -- )	Remove 2 items from the stack.
3drop	( x1 x2 x3 -- )	Remove 3 items from the stack.
dup	( x -- x x )	Duplicate the top stack item.
2dup	( x1 x2 -- x1 x2 x1 x2 )	Duplicate 2 stack items.
3dup	( x1 x2 x3 -- x1 x2 x3 x1 x2 x3 )	Duplicate 3 stack items.
?dup	( x -- x x | 0 )	Duplicate the top stack item if it is non-zero.
nip	( x1 x2 -- x2 )	Discard the second stack item.
over	( x1 x2 -- x1 x2 x1 )	Copy second stack item to top of stack.
2over	( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 )	Copy second 2 stack items.
pick	( xu ... x1 x0 u -- xu ... x1 x0 xu )	Copy u-th stack item (1 pick = over).
>r	( x -- ) (R: -- x )	Move a stack item to the return stack.
r>	( -- x ) ( R: x -- )	Move a return stack item to the stack.
r@	( -- x ) ( R: x -- x )	Copy the top of the return stack to the stack.
roll	( xu ... x1 x0 u -- xu-1 ... x1 x0 xu )	Rotate u stack items (2 roll = rot).
rot	( x1 x2 x3 -- x2 x3 x1 )	Rotate 3 stack items.
-rot	( x1 x2 x3 -- x3 x1 x2 )	Inversely rotate 3 stack items.
2rot	( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 )	Rotate 3 pairs of stack items.
swap	( x1 x2 -- x2 x1 )	Exchange the top 2 stack items.
2swap	( x1 x2 x3 x4 -- x3 x4 x1 x2 )	Exchange 2 pairs of stack items.
tuck	( x1 x2 -- x2 x1 x2 )	Copy top stack item below second item.

A typical use of stack manipulation might be to display the top stack item while preserving all stack items, as shown in this example:

---

5 77 ok dup
  					(Duplicates the top item on
the stack) 
5 77 77 ok .  				 	(Removes and
displays the top stack item) 
77 
5 77 ok

---

Creating Custom Definitions

Forth provides an easy way to create new command words from sequences of existing words. Table 4-4 shows the Forth words used to create such new words.

Table 4-4 Colon Definition Words

Command	Stack Diagram	Description
: new-name	( -- )	Start a new colon definition of the word new-name.
;	( -- )	End a colon definition.

This kind of word is called a colon definition, named after the word that is used to create them. For example, suppose you want to create a new word, add4, that will add any four numbers together and display the result. You could create the definition as follows:

---

ok : add4  + + + .  ;
ok 

---

The ; (semicolon) marks the end of the definition that defines add4 to have the behavior (+ + + .). The three addition operators (+) reduce the four stack items to a single sum on the stack; then . removes and displays that result. An example follows.

---

ok 1 2 3 3 + + + .
9
ok 1 2 3 3 add4
9
ok 

---

Definitions are forgotten if a machine reset takes place. To keep useful definitions, put them into the script or save them in a text file on a host system. This text file can then be loaded as needed. (See Chapter 5, Loading and Executing Programs for more information on loading files.)

When you type a definition from the User Interface, the ok prompt becomes a ] (right square bracket) prompt after you type the : (colon) and before you type the ; (semicolon). For example, you could type the definition for add4 like this:

---

ok : add4 
]  + + + 
]  . 
]  ; 
ok 

---

The above use of ] while inside a multi-line definition is a characteristic of Sun's implementation.

• The stack diagram shows proper use of a word, so include a stack diagram with every definition you create, even if the stack effect is nil ( -- ) . Use generous stack comments in complex definitions to trace the flow of execution. For example, when creating add4, you could define it as:

  ---

  : add4  ( n1 n2 n3 n4 -- )  + + + .  ; 

  ---

Or you could define it as follows:

---

: add4  ( n1 n2 n3 n4 -- )
   + + +			( sum )
   .			(     )
; 

---

---

Note -

The "(" is a Forth word meaning ignore the text up to the ")". Like any other Forth word, the "(" must have one or more spaces after it.

---

Using Arithmetic Functions

Single-Precision Integer Arithmetic

The commands listed in Table 4-5 perform single-precision arithmetic.

Table 4-5 Single-Precision Arithmetic Functions

Command	Stack Diagram	Description
+	( nu1 nu2 -- sum )	Adds nu1 + nu2.
-	( nu1 nu2 -- diff )	Subtracts nu1 - nu2.
*	( nu1 nu2 -- prod )	Multiplies nu1 times nu2.
*/	( n1 n2 n3 -- quot )	Calculates nu1 * nu2 / n3. Inputs, outputs and intermediate products are all one cell.
/	( n1 n2 -- quot )	Divides n1 by n2; remainder is discarded.
1+	( nu1 -- nu2 )	Adds one.
1-	( nu1 -- nu2 )	Subtracts one.
2+	( nu1 -- nu2 )	Adds two.
2-	( nu1 -- nu2 )	Subtracts two.
abs	( n -- u )	Absolute value.
bounds	( start len -- len+start start )	Converts start,len to end,start for do or ?do loop.
even	( n -- n | n+1 )	Round to nearest even integer >= n.
max	( n1 n2 -- n3 )	n3 is maximum of n1 and n2
min	( n1 n2 -- n3 )	n3 is minimum of n1 and n2
mod	( n1 n2 -- rem )	Remainder of n1 / n2.
*/mod	( n1 n2 n3 -- rem quot )	Remainder, quotient of n1 * n2 / n3.
/mod	( n1 n2 -- rem quot )	Remainder, quotient of n1 / n2.
negate	( n1 -- n2 )	Change the sign of n1.
u*	(u1 u2 -- uprod )	Multiply 2 unsigned numbers yielding an unsigned product.
u/mod	( u1 u2 -- urem uquot )	Divide unsigned one-cell number by an unsigned one-cell number; yield one-cell remainder and quotient.
<<	( x1 u -- x2 )	Synonym for lshift.
>>	( x1 u -- x2 )	Synonym for rshift.
2*	( x1 -- x2 )	Multiply by 2.
2/	( x1 -- x2 )	Divide by 2.
>>a	( x1 u -- x2 )	Arithmetic right-shift x1 by u bits.
and	( x1 x2 -- x3 )	Bitwise logical AND.
invert	( x1 -- x2 )	Invert all bits of x1.
lshift	( x1 u -- x2 )	Left-shift x1 by u bits. Zero-fill low bits.
not	( x1 -- x2 )	Synonym for invert.
or	( x1 x2 -- x3 )	Bitwise logical OR.
rshift	( x1 u -- x2 )	Right-shift x1 by u bits. Zero-fill high bits.
u2/	( x1 -- x2 )	Logical right shift 1 bit; zero shifted into high bit.
xor	( x1 x2 -- x3 )	Bitwise exclusive OR.

Double Number Arithmetic

The commands listed in Table 4-6 perform double number arithmetic.

Table 4-6 Double Number Arithmetic Functions

Command	Stack Diagram	Description
d+	( d1 d2 -- d.sum )	Add d1 to d2 yielding double number d.sum.
d-	( d1 d2 --d.diff )	Subtract d2 from d1 yielding double number d.diff.
fm/mod	( d n -- rem quot )	Divide d by n.
m*	( n1 n2 -- d )	Signed multiply with double-number product.
s>d	( n1 -- d1 )	Convert a number to a double number.
sm/rem	( d n -- rem quot )	Divide d by n, symmetric division.
um*	( u1 u2 -- ud )	Unsigned multiply yielding unsigned double number product.
um/mod	( ud u -- urem uprod )	Divide ud by u.

Data Type Conversion

The commands listed in Table 4-7 perform data type conversion.

Table 4-7 32-Bit Data Type Conversion Functions

Command	Stack Diagram	Description
bljoin	( b.low b2 b3 b.hi -- quad )	Join four bytes to form a quadlet
bwjoin	( b.low b.hi -- word )	Join two bytes to form a doublet.
lbflip	( quad1 -- quad2 )	Reverse the bytes in a quadlet
lbsplit	( quad -- b.low b2 b3 b.hi )	Split a quadlet into four bytes.
lwflip	( quad1 -- quad2 )	Swap the doublets in a quadlet.
lwsplit	( quad -- w.low w.hi )	Split a quadlet into two doublets.
wbflip	( word1 -- word2 )	Swap the bytes in a doublet.
wbsplit	( word -- b.low b.hi )	Split a doublet into two bytes.
wljoin	( w.low w.hi -- quad )	Join two doublets to form a quadlet.

The data type conversion commands listed in Table 4-8 are available only on 64-bit OpenBoot implementations.

Table 4-8 64-Bit Data Type Conversion Functions

Command	Stack Diagram	Description
bxjoin	( b.lo b.2 b.3 b.4 b.5 b.6 b.7 b.hi -- o )	Join eight bytes to form an octlet.
lxjoin	( quad.lo quad.hi -- o )	Join two quadlets to form an octlet.
wxjoin	( w.lo w.2 w.3 w.hi -- o )	Join four doublets to form an octlet.
xbflip	( oct1 -- oct2 )	Reverse the bytes in an octlet.
xbsplit	( o -- b.lo b.2 b.3 b.4 b.5 b.6 b.7 b.hi )	Split an octlet into eight bytes.
xlflip	( oct1 -- oct2 )	Reverse the quadlets in an octlet. The bytes in each quadlet are not reversed.
xlsplit	( o -- quad.lo quad.hi )	Split on octlet into two quadlets.
xwflip	( oct1 -- oct2 )	Reverse the doublets in an octlet. The bytes in each doublet are not reversed.
xwsplit	( o -- w.lo w.2 w.3 w.hi )	Split an octlet into four doublets.

Address Arithmetic

The commands listed in Table 4-9 perform address arithmetic.

Table 4-9 Address Arithmetic Functions

Command	Stack Diagram	Description
aligned	( n1 -- n1 | a-addr)	Increase n1 if necessary to yield a variable aligned address.
/c	( -- n )	The number of address units to a byte: 1.
/c*	( nu1 -- nu2 )	Synonym for chars.
ca+	( addr1 index -- addr2 )	Increment addr1 by index times the value of /c.
ca1+	( addr1 -- addr2 )	Synonym for char+.
cell+	( addr1 -- addr2 )	Increment addr1 by the value of /n.
cells	( nu1 -- nu2 )	Multiply nu1 by the value of /n.
char+	( addr1 -- addr2 )	Increment addr1 by the value of /c.
chars	( nu1 -- nu2 )	Multiply nu1 by the value of /c.
/l	( -- n )	Number of address units to a quadlet; typically 4.
/l*	( nu1 -- nu2 )	Multiply nu1 by the value of /l.
la+	( addr1 index -- addr2 )	Increment addr1 by index times the value of /l.
la1+	( addr1 -- addr2 )	Increment addr1 by the value of /l.
/n	( -- n )	Number of address units in a cell.
/n*	( nu1 -- nu2 )	Synonym for cells.
na+	( addr1 index -- addr2 )	Increment addr1 by index times the value of /n.
na1+	( addr1 -- addr2 )	Synonym for cell+.
/w	( -- n )	Number of address units to a doublet; typically 2.
/w*	( nu1 -- nu2 )	Multiply nu1 by the value of /w.
wa+	( addr1 index -- addr2 )	Increment addr1 by index times the value of /w.
wa1+	( addr1 -- addr2 )	Increment addr1 by the value of /w.

The address arithmetic commands listed in Table 4-10 are available only on 64-bit OpenBoot implementations.

Table 4-10 64-Bit Address Arithmetic Functions

Command	Stack Diagram	Description
/x	( -- n )	Number of address units in an octlet, typically eight.
/x*	( nu1 -- nu2 )	Multiply nu1 by the value of /x.
xa+	( addr1 index -- addr2 )	Increment addr1 by index times the value of /x.
xa1+	( addr1 -- addr2 )	Increment addr1 by the value of /x.

Accessing Memory

Virtual Memory

The User Interface provides interactive commands for examining and setting memory. With it, you can:

• Read and write to any virtual address.

• Map virtual addresses to physical addresses.

Memory operators let you read from and write to any memory location. All memory addresses shown in the examples that follow are virtual addresses.

A variety of 8-bit, 16-bit, and 32-bit (and in some systems, 64-bit) operations are provided. In general, a c (character) prefix indicates an 8-bit (one byte) operation; a w (word) prefix indicates a 16-bit (doublet) operation; an l (longword) prefix indicates a 32-bit (quadlet) operation; and an x prefix indicates a 64-bit (octlet) operation.

waddr, qaddr, and oaddr indicate addresses with alignment restrictions. For example, qaddr indicates 32-bit (4 byte) alignment; on many systems such an address must be a multiple of 4, as shown in the following example:

---

ok 4028 l@ 
ok 4029 l@ 
Memory address not aligned 
ok 

---

Forth, as implemented in OpenBoot, adheres closely to the ANS Forth Standard. If you explicitly want a 16-bit fetch, a 32-bit fetch or (on some systems) a 64-bit fetch, use w@, l@ or x@ instead of @. Other memory and device register access commands also follow this convention.

Table 4-11 lists commands used to access memory.

Table 4-11 Memory Access Commands

Command	Stack Diagram	Description
!	( x a-addr -- )	Store a number at a-addr.
+!	( nu a-addr -- )	Add nu to the number stored at a-addr.
@	( a-addr -- x )	Fetch a number from a-addr.
2!	( x1 x2 a-addr -- )	Store 2 numbers at a-addr, x2 at lower address.
2@	( a-addr -- x1 x2 )	Fetch 2 numbers from a-addr, x2 from lower address.
blank	( addr len -- )	Set len bytes of memory beginning at addr to the space character (decimal 32).
c!	( byte addr -- )	Store byte at addr.
c@	( addr -- byte )	Fetch a byte from addr.
cpeek	( addr -- false | byte true )	Attempt to fetch the byte at addr. Return the data and true if the access was successful. Return false if a read access error occurred.
cpoke	( byte addr -- okay? )	Attempt to store the byte to addr. Return true if the access was successful. Return false if a write access error occurred.
comp	( addr1 addr2 len -- diff? )	Compare two byte arrays. diff? is 0 if the arrays are identical, diff? is -1 if the first byte that is different is lesser in the string at addr1, diff? is 1 otherwise.
dump	( addr len -- )	Display len bytes of memory starting at addr.
erase	( addr len -- )	Set len bytes of memory beginning at addr to 0.
fill	( addr len byte -- )	Set len bytes of memory beginning at addr to the value byte.
l!	( q qaddr -- )	Store a quadlet q at qaddr.
l@	( qaddr -- q )	Fetch a quadlet q from qaddr.
lbflips	( qaddr len -- )	Reverse the bytes in each quadlet in the specified region.
lwflips	( qaddr len -- )	Swap the doublets in each quadlet in specified region.
lpeek	( qaddr -- false | quad true )	Attempt to fetch the quadlet at qaddr. Return the data and true if the access was successful. Return false if a read access error occurred.
lpoke	( q qaddr -- okay? )	Attempt to store the quadlet 8 at qaddr. Return true if the access was successful. Return false if a a write access error occurred.
move	( src-addr dest-addr len -- )	Copy len bytes from src-addr to dest-addr.
off	( a-addr -- )	Store false at a-addr.
on	( a-addr -- )	Store true at a-addr.
unaligned-l!	( q addr -- )	Store a quadlet q, any alignment
unaligned-l@	( addr -- q )	Fetch a quadlet q, any alignment.
unaligned-w!	( w addr -- )	Store a doublet w, any alignment.
unaligned-w@	( addr -- w )	Fetch a doublet w, any alignment.
w!	( w waddr -- )	Store a doublet w at waddr.
w@	( waddr -- w)	Fetch a doublet w from waddr.
<w@	( waddr -- n )	Fetch doublet n from waddr, sign-extended.
wbflips	( waddr len -- )	Swap the bytes in each doublet in the specified region.
wpeek	( waddr -- false | w true )	Attempt to fetch the doublet w at waddr. Return the data and true if the access was successful. Return false if a read access error occurred.
wpoke	( w waddr -- okay? )	Attempt to store the doublet w to waddr. Return true if the access was successful. Return false if a write access error occurred.

The memory access commands listed in Table 4-12 are available only on 64-bit OpenBoot implementations.

Table 4-12 64-Bit Memory Access Functions

Command	Stack Diagram	Description
<l@	( qaddr -- n )	Fetch quadlet from qaddr, sign-extended.
x@	( oaddr -- o )	Fetch octlet from an octlet aligned address.
x!	( o oaddr -- )	Store octlet to an octlet aligned address.
xbflips	( oaddr len -- )	Reverse the bytes in each octlet in the given region.The behavior is undefined if len is not a multiple of /x.
xlflips	( oaddr len -- )	Reverse the quadlets in each octlet in the given region. The bytes in each quadlet are not reversed. The behavior is undefined if len is not a multiple of /x.
xwflips	( oaddr len -- )	Reverse the doublets in each octlet in the given region. The bytes in each doublet are not reversed. The behavior is undefined if len is not a multiple of /x.

The dump command is particularly useful. It displays a region of memory as both bytes and ASCII values. The example below displays the contents of 20 bytes of memory starting at virtual address 10000.

---

ok 10000 20 dump						
(Display 20 bytes of memory starting at virtual address
10000)
       \/ 1  2  3  4  5  6  7   8  9  a  b  c  d  e  f  v123456789abcdef
 10000 05 75 6e 74 69 6c 00 40  4e d4 00 00 da 18 00 00 .until.@NT..Z...
 10010 ce da 00 00 f4 f4 00 00  fe dc 00 00 d3 0c 00 00 NZ..tt..~\..S...
ok 

---

Some implementations support variants of dump that display memory as 16-, 32- and 64-bit values. You can use sifting dump (see "Searching the Dictionary") to find out if your system has such variants.

If you try to access an invalid memory location (with @, for example), the operation may abort and display an error message, such as Data Access Exception or Bus Error.

Table 4-13 lists memory mapping commands.

Table 4-13 Memory Mapping Commands

Command	Stack Diagram	Description
alloc-mem	( len -- a-addr )	Allocate len bytes of memory; return the virtual address.
free-mem	( a-addr len -- )	Free memory allocated by alloc-mem.

The following screen is an example of the use of alloc-mem and free-mem.

• alloc-mem allocates 4000 bytes of memory, and the starting address (ef7a48) of the reserved area is displayed.

• dump displays the contents of 20 bytes of memory starting at ef7a48.

• This region of memory is then filled with the value 55.

• Finally, free-mem returns the 4000 allocated bytes of memory starting at ef7a48.

  ---

  ok
  ok 4000 alloc-mem . 
  ef7a48 
  ok 
  ok ef7a48 constant temp 
  ok temp 20 dump 
          0  1  2  3  4  5  6  7  \/  9  a  b  c  d  e  f   01234567v9abcdef
  ef7a40  00 00 f5 5f 00 00 40 08  ff ef c4 40 ff ef 03 c8  ..u_..@..oD@.o.H
  ef7a50  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
  ef7a60  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  ................
  ok temp 20 55 fill 
  ok temp 20 dump 
          0  1  2  3  4  5  6  7  \/  9  a  b  c  d  e  f   01234567v9abcdef
  ef7a40  00 00 f5 5f 00 00 40 08  55 55 55 55 55 55 55 55  ..u_..@.UUUUUUUU
  ef7a50  55 55 55 55 55 55 55 55  55 55 55 55 55 55 55 55  UUUUUUUUUUUUUUUU
  ef7a60  55 55 55 55 55 55 55 55  00 00 00 00 00 00 00 00  UUUUUUUU........
  ok 
  ok temp 4000 free-mem 
  ok 

  ---

Device Registers

Device registers cannot be reliably accessed using the virtual memory access operators discussed in the last section. There are special operators for accessing device registers, and these operators require that the machine be properly set up prior to their use. For a detailed explanation of this topic, see Writing FCode 3.x Programs.

Using Defining Words

The dictionary contains all the available Forth words. Forth defining words create new Forth words.

Defining words require two stack diagrams. The first diagram shows the stack effect when the new word is created. The second (or "Execution:") diagram shows the stack effect when that word is later executed.

Table 4-14 lists the defining words that you can use to create new Forth words.

If a Forth command is created with the same name as an existing command, the new command will be created normally. Depending on the implementation, a warning message "new-name isn't unique" may be displayed. Previous uses of that command name will be unaffected. Subsequent uses of that command name will use the latest definition of that command name. (To correct the original definition such that all uses of the command name get the corrected behavior, make the correction with patch. (See "Using patch and (patch)")

Table 4-14 Defining Words

Command	Stack Diagram	Description
: name	( -- ) (E: ... -- ??? )	Begin creation of a colon definition.
;	( -- )	End creation of a colon definition.
alias new-name old-name	( -- ) (E: ... -- ??? )	Create new-name with the same behavior as old-name.
buffer: name	( size -- ) (E: -- a-addr )	Create a named data buffer. name returns a-addr.
constant name	( x -- ) (E: -- x )	Create a constant (for example, 3 constant bar).
2constant name	( x1 x2 -- ) (E: -- x1 x2 )	Create a 2-number constant.
create name	( -- ) (E: -- a-addr )	Create a new command whose behavior will be set by further commands.
$create	( name-str name-len -- )	Call create with the name specified by name-string.
defer name	( -- ) (E: ... -- ??? )	Create a command with alterable behavior. Alter with to.
does>	( ... -- ... a-addr ) (E: ... -- ??? )	Specify the run-time behavior of a created word.
field name	( offset size -- offset+size ) (E: addr -- addr+offset )	Create a field offset pointer named name.
struct	( -- 0 )	Start a structfield definition.
value name	( x -- ) (E: -- x )	Create a named variable. Change with to.
variable name	( -- ) (E: -- a-addr )	Create a named variable. name returns a-addr.

value lets you create a name for a numerical value that can be changed. Later execution of that name leaves the assigned value on the stack. The following example creates a word named foo with an initial value of 22, and then calls foo to use its value in an arithmetic operation.

---

ok 22 value foo
ok foo 3 + .
25
ok 

---

The value can be changed with the word to. For example:

---

ok 43 value thisval
ok thisval .
43
ok 10 to thisval
ok thisval .
10
ok 

---

Words created with value are convenient, because you do not have to use @ to retrieve their values.

The defining word variable creates a name with an associated one-cell memory location. Later execution of that name leaves the address of the memory on the stack. @ and ! are used to read or write to that address. For example:

---

ok variable bar
ok 33 bar !
ok bar @ 2 + .
35
ok 

---

The defining word defer creates a word whose behavior can be changed later, by creating a slot which can be loaded with different behaviors at different times. For example:

---

ok hex
ok defer printit
ok ['] .d  to  printit
ok ff printit
255
ok : myprint ( n -- ) ." It is " .h
] ." in hex " ;
ok ['] myprint to printit
ok ff printit
It is ff in hex
ok 

---

Searching the Dictionary

The dictionary contains all the available Forth words. Table 4-15 lists some useful tools you can use to search the dictionary. Please note that some of these tools work only with methods or commands while others work with all types of words (including, for example, variables and values).

Table 4-15 Dictionary Searching Commands

Command	Stack Diagram	Description
' name	( -- xt )	Find the named word in the dictionary. Returns the execution token. Use outside definitions.
['] name	( -- xt )	Similar to ' but is used either inside or outside definitions.
.calls	( xt -- )	Display a list of all commands which use the execution token xt.
$find	( str len -- xt true | str len false )	Search for word named by str,len. If found, leave xt and true on stack. If not found, leave name string and false on stack.
find	( pstr -- xt n | pstr false )	Search for word named by pstr. If found, leave xt and true on stack. If not found, leave name string and false on stack. (We recommend using $find to avoid using packed strings.)
see thisword	( -- )	Decompile the specified word.
(see)	( xt -- )	Decompile the word whose execution token is xt.
$sift	( text-addr text-len -- )	Display all command names containing text-string.
sifting text	( -- )	Display all command names containing text. text contains no spaces.
words	( -- )	Display the names of words in the dictionary as described below.

Before you can understand the operation of the dictionary searching tools, you need to understand how words become visible. If there is an active package at the time a word is defined, the new word becomes a method of the active package, and is visible only when that package is the active package. The commands dev and find-device can be used to select or change the active package. The command device-end deselects the currently active package leaving no active package.

If there is no active package at the time a word is defined, the word is globally visible (i.e. not specific to a particular package and always available).

The dictionary searching commands first search through the words of the active package, if there is one, and then through the globally visible words.

---

Note -

The Forth commands only and also will affect which words are visible.

---

.calls can be used to locate all of the Forth commands that use a specified word in their definition. .calls takes an execution token from the stack and searches the entire dictionary to produce a listing of the names and addresses of every Forth command which uses that execution token. For example:

---

ok ' input .calls
	Called from input at 1e248d8
	Called from io at 1e24ac0
	Called from install-console at 1e33598
	Called from install-console at 1e33678
ok

---

see, used in the form:

see thisword

displays a "pretty-printed" listing of the source for thisword (without the comments, of course). For example:

---

ok see see
: see 
	¢ [¢] (see) catch if 
		drop 
	then 
; 
ok

---

For more details on the use of see, refer to "Using the Forth Language Decompiler".

sifting takes a string from the input stream and searches vocabularies in the dictionary search order to find every command name that contains the specified string as shown in the following screen.

---

ok sifting input

		In vocabulary options 
(1e333f8) input-device 
		In vocabulary forth 
(1e2476c) input							(1e0a9b4) set-input							(1e0a978) restore-input 
(1e0a940) save-input							(1e0a7f0) more-input?							(1e086cc) input-file 
ok

---

words displays all the visible word names in the dictionary, starting with the most recent definition. If a node is currently selected (as with dev), the list produced by words is limited to the words in that selected node.

Compiling Data Into the Dictionary

The commands listed in Table 4-16 control the compilation of data into the dictionary.

Table 4-16 Dictionary Compilation Commands

Command	Stack Diagram	Description
,	( n -- )	Place a number in the dictionary.
c,	( byte -- )	Place a byte in the dictionary.
w,	( word -- )	Place a 16-bit number in the dictionary.
l,	( quad -- )	Place a 32-bit number in the dictionary.
[	( -- )	Begin interpreting.
]	( -- )	End interpreting, resume compilation.
allot	( n -- )	Allocate n bytes in the dictionary.
>body	( xt -- a-addr )	Find the data field address from the execution token.
body>	( a-addr -- xt )	Find the execution token from the data field address.
compile	( -- )	Compile the next word at run time. (Recommend using postpone instead.)
[compile] name	( -- )	Compile the next (immediate) word. (Recommend using postpone instead.)
here	( -- addr )	Address of top of dictionary.
immediate	( -- )	Mark the last definition as immediate.
to name	( n -- )	Install a new action in a defer word or value.
literal	( n -- )	Compile a number.
origin	( -- addr )	Return the address of the start of the Forth system.
patch new-word old-word word-to-patch	( -- )	Replace old-word with new-word in word-to-patch.
(patch)	( new-n old-n xt -- )	Replace old-n with new-n in word indicated by xt.
postpone name	( -- )	Delay the execution of the word name.
recurse	( ... -- ??? )	Compile a recursive call to the word being compiled.
recursive	( -- )	Make the name of the colon definition being compiled visible in the dictionary, and thus allow the name of the word to be used recursively in its own definition.
state	( -- addr )	Variable that is non-zero in compile state.

The dictionary compilation commands listed in Table 4-17 are available only on 64-bit OpenBoot implementations.

Table 4-17 64-Bit Dictionary Compilation Commands

Command	Stack Diagram	Description
x,	( o -- )	Compile an octlet, o, into the dictionary (doublet-aligned).

Displaying Numbers

Basic commands to display stack values are shown in Table 4-18.

Table 4-18 Basic Number Display

Command	Stack Diagram	Description
.	( n -- )	Display a number in the current base.
.r	( n size -- )	Display a number in a fixed width field.
.s	( -- )	Display contents of data stack.
showstack	( ??? -- ??? )	Execute .s automatically before each ok prompt.
noshowstack	( ??? -- ??? )	Turn off automatic display of the stack before each ok prompt
u.	( u -- )	Display an unsigned number.
u.r	( u size -- )	Display an unsigned number in a fixed width field.

The .s command displays the entire stack contents without disturbing them. It can usually be used safely for debugging purposes. (This is the function that showstack performs automatically.)

Changing the Number Base

You can print numbers in a specific number base or change the operating number base using the commands in Table 4-19.

Table 4-19 Changing the Number Base

Command	Stack Diagram	Description
.d	( n -- )	Display n in decimal without changing base.
.h	( n -- )	Display n in hex without changing base.
base	( -- addr )	Variable containing number base.
decimal	( -- )	Set the number base to 10.
d# number	( -- n )	Interpret number in decimal; base is unchanged.
hex	( -- )	Set the number base to 16.
h# number	( -- n )	Interpret number in hex; base is unchanged.

The d# and h# commands are useful when you want to input a number in a specific base without explicitly changing the current base. For example:

---

ok decimal       (Changes base to decimal)
ok 4 h# ff 17 2
4 255 17 2 ok 

---

The .d and .h commands act like "." but display the value in decimal or hexadecimal, respectively, regardless of the current base setting. For example:

---

ok hex
ok ff .  ff .d
ff 255 

---

Controlling Text Input and Output

This section describes text and character input and output commands.

Table 4-20 lists commands to control text input.

Table 4-20 Controlling Text Input

Command	Stack Diagram	Description
( ccc )	( -- )	Create a comment. Conventionally used for stack diagrams.
\ rest-of-line	( -- )	Treat the rest of the line as a comment.
ascii ccc	( -- char )	Get numerical value of first ASCII character of next word.
accept	( addr len1 -- len2 )	Get a line of edited input from the console input device; store at addr. len1 is the maximum allowed length. len2 is the actual length received.
expect	( addr len -- )	Get and display a line of input from the console; store at addr. (Recommend using accept instead.)
key	( -- char )	Read a character from the console input device.
key?	( -- flag )	True if a key has been typed on the console input device.
parse	( char -- str len )	Parse text from the input buffer delimited by char.
parse-word	( -- str len )	Skip leading spaces and parse text from the input buffer delimited by white space.
word	( char -- pstr )	Collect a string delimited by char from the input buffer and place it as a packed string in memory at pstr. (Recommend using parse instead.)

Comments are used with Forth source code (generally in a text file) to describe the function of the code. The ( (open parenthesis) is the Forth word that begins a comment. Any character up to the closing parenthesis ) is ignored by the Forth interpreter. Stack diagrams are one example of comments using (.

---

Note -

Remember to follow the( with a space, so that it is recognized as a Forth word.

---

\ (backslash) indicates a comment terminated by the end of the line of text.

key waits for a key to be pressed, then returns the ASCII value of that key on the stack.

ascii, used in the form ascii x, returns on the stack the numerical code of the character x.

key? looks at the keyboard to see whether the user has recently typed any key. It returns a flag on the stack: true if a key has been pressed and false otherwise. See "Conditional Flags" for a discussion on the use of flags.

Table 4-21 lists general-purpose text display commands.

Table 4-21 Displaying Text Output

Command	Stack Diagram	Description
." ccc"	( -- )	Compile a string for later display.
(cr	( -- )	Move the output cursor back to the beginning of the current line.
cr	( -- )	Terminate a line on the display and go to the next line.
emit	( char -- )	Display the character.
exit?	( -- flag )	Enable the scrolling control prompt: More [<space>,<cr>,q] ? The return flag is true if the user wants the output to be terminated.
space	( -- )	Display a space character.
spaces	( +n -- )	Display +n spaces.
type	( addr +n -- )	Display the +n characters beginning at addr.

cr sends a carriage-return/linefeed sequence to the console output device. For example:

---

ok 3 . 44 . cr 5 .
3 44
5
ok 

---

emit displays the letter whose ASCII value is on the stack.

---

ok ascii a 
61 ok 42
61 42 ok emit emit
Ba
ok 

---

Table 4-22 shows commands used to manipulate text strings.

Table 4-22 Manipulating Text Strings

Command	Stack Diagram	Description
",	( addr len -- )	Compile an array of bytes from addr of length len, at the top of the dictionary as a packed string.
" ccc"	( -- addr len )	Collect an input stream string, either interpreted or compiled.
." ccc"		Display the string ccc .
.( ccc)	( -- )	Display the string ccc immediately.
-trailing	( addr +n1 -- addr +n2 )	Remove trailing spaces.
bl	( -- char )	ASCII code for the space character; decimal 32.
count	( pstr -- addr +n )	Unpack a packed string.
lcc	( char -- lowercase-char )	Convert a character to lowercase.
left-parse-string	( addr len char -- addrR lenR addrL lenL )	Split a string at char (which is discarded).
pack	( addr len pstr -- pstr )	Store the string addr,len as a packed string at pstr.
upc	( char -- uppercase-char )	Convert a character to uppercase.

Some string commands specify an address (the location in memory where the characters reside) and a length (the number of characters in the string). Other commands use a packed string or pstr, which is a location in memory containing a byte for the length, immediately followed by the characters. The stack diagram for the command indicates which form is used. For example, count converts a packed string to an address-length string.

The command ." is used in the form: ." string". It outputs text immediately when it is encountered by the interpreter. A " (double quotation mark) marks the end of the text string. For example:

---

ok  : testing 34 .  ." This is a test"  55 . ;
ok
ok testing
34 This is a test55
ok 

---

When " is used outside a colon definition, only two interpreted strings of up to 80 characters each can be assembled concurrently. This limitation does not apply in colon definitions.

Redirecting Input and Output

Normally, OpenBoot uses a keyboard for command input, and a frame buffer with a connected display screen for display output. (Server systems may use an ASCII terminal connected to a serial port. For more information on how to connect a terminal to your system, see your system's installation manual.) You can redirect the input, the output, or both, to a serial port. This may be useful, for example, when debugging a frame buffer.

Table 4-23 lists commands you can use to redirect input and output.

Table 4-23 I/O Redirection Commands

Command	Stack Diagram	Description
input	( device -- )	Select device, for example ttya, keyboard, or device-specifier, for subsequent input.
io	( device -- )	Select device for subsequent input and output.
output	( device -- )	Select device, for example ttya, keyboard, or device-specifier, for subsequent output.

The commands input and output temporarily change the current devices for input and output. The change takes place as soon as you enter a command; you do not have to reset your system. A system reset or power cycle causes the input and output devices to revert to the default settings specified in the NVRAM configuration variables input-device and output-device. These variables can be modified, if needed (see Chapter 3, Setting Configuration Variables).

input must be preceded by one of the following: keyboard, ttya, ttyb, or device-specifier text string. For example, if input is currently accepted from the keyboard, and you want to make a change so that input is accepted from a terminal connected to the serial port ttya, type:

---

ok ttya input
ok

---

At this point, the keyboard becomes nonfunctional (except perhaps for Stop-A), but any text entered from the terminal connected to ttya is processed as input. All commands are executed as usual.

To resume using the keyboard as the input device, use the terminal keyboard to type:

---

ok keyboard input
ok

---

Similarly, output must be preceded by one of the following: screen, ttya, or ttyb or device-specifier. For example, if you want to send output to a serial port instead of the normal display screen, type:

---

ok ttya output
ok

---

The screen does not show the answering ok prompt, but the terminal connected to the serial port shows the ok prompt and all further output as well.

io is used in the same way, except that it changes both the input and output to the specified place. For example:

---

ok ttya io
ok 

---

Generally, the argument to input, output, and io is a device-specifier, which can be either a device path name or a device alias. The device must be specified as a Forth string, using double quotation marks ("), as shown in the two examples below:

---

ok " /sbus/cgsix" output

---

or:

---

ok " screen" output

---

In the preceding examples, keyboard, screen, ttya, and ttyb are predefined Forth words that put their corresponding device alias string on the stack.

Command Line Editor

OpenBoot implements a command line editor (similar to EMACS, a common text editor), some optional extensions and an optional history mechanism for the User Interface. You use these tools to re-execute previous commands without retyping them, to edit the current command line to fix typing errors, or to recall and change previous commands.

Table 4-24 lists line-editing commands available at the ok prompt.

Table 4-24 Required Command Line Editor Keystroke Commands

Keystroke	Description
Return (Enter)	Finishes editing of the line and submits the entire visible line to the interpreter regardless of the current cursor position.
Control-B	Moves backward one character.
Escape B	Moves backward one word.
Control-F	Moves forward one character.
Escape F	Moves forward one word.
Control-A	Moves backward to beginning of line.
Control-E	Moves forward to end of line.
Delete	Erases previous character.
Backspace	Erases previous character.
Control-H	Erases previous character.
Escape H	Erases from beginning of word to just before the cursor, storing erased characters in a save buffer.
Control-W	Erases from beginning of word to just before the cursor, storing erased characters in a save buffer.
Control-D	Erases next character.
Escape D	Erases from cursor to end of the word, storing erased characters in a save buffer.
Control-K	Erases from cursor to end of line, storing erased characters in a save buffer.
Control-U	Erases entire line, storing erased characters in a save buffer.
Control-R	Retypes the line.
Control-Q	Quotes next character (allows you to insert control characters).
Control-Y	Inserts the contents of the save buffer before the cursor.

The command line history extension saves previously-typed commands in an EMACS-like command history ring that contains at least 8 entries. Commands may be recalled by moving either forward or backward around the ring. Once recalled, a command may be edited and/or resubmitted (by typing the Return key). The command line history extension keys are:

Table 4-25 Command Line History Keystroke Commands

Keystroke	Description
Control-P	Selects and displays the previous command in the command history ring.
Control-N	Selects and displays the next command in the command history ring.
Control-L	Displays the entire command history ring.

The command completion extension enables the system to complete long Forth word names by searching the dictionary for one or more matches based on the already-typed portion of a word. When you type a portion of a word followed by the command completion keystroke, Control-Space, the system behaves as follows:

• If the system finds exactly one matching word, the remainder of the word is automatically displayed.

• If the system finds several possible matches, the system displays all of the characters that are common to all of the possibilities.

• If the system cannot find a match for the already-typed characters, the system deletes characters from the right until there is at least one match for the remaining characters.

• The system beeps if it cannot determine an unambiguous match.

The command completion extension keys are:

Table 4-26 Command Completion Keystroke Commands

Keystroke	Description
Control-Space	Complete the name of the current word.
Control-?	Display all possible matches for the current word.
Control-/	Display all possible matches for the current word.

Conditional Flags

Forth conditionals use flags to indicate true/false values. A flag can be generated in several ways, based on testing criteria. The flag can then be displayed from the stack with the word ".", or it can be used as input to a conditional control command. Control commands can cause one behavior if a flag is true and another behavior if the flag is false. Thus, execution can be altered based on the result of a test.

A 0 value indicates that the flag value is false. A -1 or any other nonzero number indicates that the flag value is true.

Table 4-27 lists commands that perform relational tests, and leave a true or false flag result on the stack.

Table 4-27 Comparison Commands

Command	Stack Diagram	Description
<	( n1 n2 -- flag )	True if n1 < n2.
<=	( n1 n2 -- flag )	True if n1 <= n2.
<>	( n1 n2 -- flag )	True if n1 is not equal to n2.
=	( n1 n2 -- flag )	True if n1 = n2.
>	( n1 n2 -- flag )	True if n1 > n2.
>=	( n1 n2 -- flag )	True if n1 >= n2.
0<	( n -- flag )	True if n < 0.
0<=	( n -- flag )	True if n <= 0.
0<>	( n -- flag )	True if n <> 0.
0=	( n -- flag )	True if n = 0 (also inverts any flag).
0>	( n -- flag )	True if n > 0.
0>=	( n -- flag )	True if n >= 0.
between	( n min max -- flag )	True if min <= n <= max.
false	( -- 0 )	The value FALSE, which is 0.
true	( -- -1 )	The value TRUE, which is -1.
u<	( u1 u2 -- flag )	True if u1 < u2, unsigned.
u<=	( u1 u2 -- flag )	True if u1 <= u2, unsigned.
u>	( u1 u2 -- flag )	True if u1 > u2, unsigned.
u>=	( u1 u2 -- flag )	True if u1 >= u2, unsigned.
within	( n min max -- flag )	True if min <= n < max.

> takes two numbers from the stack, and returns true (-1) on the stack if the first number was greater than the second number, or returns false (0) otherwise. An example follows:

---

ok 3 6 > .
0                (3 is not greater than 6) 
ok 

---

0= takes one item from the stack, and returns true if that item was 0 or returns false otherwise. This word inverts any flag to its opposite value.

Control Commands

The following sections describe words used in a Forth program to control the flow of execution.

The if-else-then Structure

The commands if, else and then provide a simple control structure.

The commands listed in Table 4-28 control the flow of conditional execution.

Table 4-28 ifelsethen Commands

Command	Stack Diagram	Description
if	( flag -- )	Execute the following code when flag is true.
else	( -- )	Execute the following code when flag is false.
then	( -- )	Terminate ifelsethen.

The format for using these commands is:

---

flag	if
	(do this if true)
then	
(continue normally) 

---

or

---

flag	if
	(do this if true)
else
	(do this if false)
then	
(continue normally) 

---

The if command consumes a flag from the stack. If the flag is true (nonzero), the commands following the if are performed. Otherwise, the commands (if any) following the else are performed.

---

ok : testit  ( n -- ) 
] 5 >  if  ." good enough " 
] else  ." too small " 
] then 
] ." Done. "  ; 
ok
ok 8 testit
good enough Done. 
ok 2 testit 
too small Done. 
ok 

---

---

Note -

The ] prompt reminds you that you are part way through creating a new colon definition. It reverts to ok after you finish the definition with a semicolon.

---

The case Statement

A high-level case command is provided for selecting alternatives with multiple possibilities. This command is easier to read than deeply-nested ifthen commands.

Table 4-29 lists the conditional case commands.

Table 4-29 case Statement Commands

Command	Stack Diagram	Description
case	( selector -- selector )	Begin a caseendcase conditional.
endcase	( selector -- )	Terminate a caseendcase conditional.
endof	( -- )	Terminate an ofendof clause in a case...endcase
of	( selector test-value -- selector | {empty} )	Begin an ofendof clause in a case conditional.

Here is a simple example of a case command:

---

ok : testit  ( testvalue -- )
]	case
]		0  of  ." It was zero "										endof 
]		1  of  ." It was one "										endof 
]		ff of  ." Correct "										endof 
]		-2 of  ." It was minus-two "										endof 
]		( default )  ." It was this value: "  dup . 
]	endcase   ." All done."  ; 
ok
ok 1 testit
It was one All done.
ok ff testit
Correct All done.
ok 4 testit
It was this value: 4 All done.
ok 

---

---

Note -

The (optional) default clause can use the test value which is still on the stack, but should not remove it (use the phrase "dup ." instead of "."). A successful of clause automatically removes the test value from the stack.

---

The begin Loop

A begin loop executes the same commands repeatedly until a certain condition is satisfied. Such a loop is also called a conditional loop.

Table 4-30 lists commands to control the execution of conditional loops.

Table 4-30 begin (Conditional) Loop Commands

Command	Stack Diagram	Description
again	( -- )	End a beginagain infinite loop.
begin	( -- )	Begin a beginwhilerepeat, beginuntil, or beginagain loop.
repeat	( -- )	End a beginwhilerepeat loop.
until	( flag -- )	Continue executing a beginuntil loop until flag is true.
while	( flag -- )	Continue executing a beginwhilerepeat loop while flag is true.

There are two general forms:

---

begin 		any commandsflag until 

---

and

---

begin			any commands				flag		while
			more commands						repeat

---

In both cases, the commands in the loop are executed repeatedly until the proper flag value causes the loop to be terminated. Then execution continues normally with the command following the closing command word (until or repeat).

In the beginuntil case, until removes a flag from the top of the stack and inspects it. If the flag is false, execution continues just after the begin, and the loop repeats. If the flag is true, the loop is exited.

In the beginwhilerepeat case, while removes a flag from the top of the stack and inspects it. If the flag is true, the loop continues by executing the commands just after the while. The repeat command automatically sends control back to begin to continue the loop. If the flag is false when while is encountered, the loop is exited immediately; control goes to the first command after the closing repeat.

An easy mnemonic for either of these loops is: If true, fall through.

A simple example follows.

---

ok begin 4000 c@ . key? until   (
repeat until any key is pressed)
43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43
ok 

---

The loop starts by fetching a byte from location 4000 and displaying the value. Then, the key? command is called, which leaves a true on the stack if the user has pressed any key, and false otherwise. This flag is consumed by until and, if the value is false, then the loop continues. Once a key is pressed, the next call to key? returns true, and the loop terminates.

Unlike many versions of Forth, the User Interface allows the interactive use of loops and conditionals -- that is, without first creating a definition.

The do Loop

A do loop (also called a counted loop) is used when the number of iterations of the loop can be calculated in advance. A do loop normally exits just before the specified ending value is reached.

Table 4-31 lists commands to control the execution of counted loops.

Table 4-31 do (Counted) Loop Commands

Command	Stack Diagram	Description
+loop	( n -- )	End a do+loop construct; add n to loop index and return to do (if n < 0, index goes from start to end inclusive).
?do	( end start -- )	Begin ?doloop to be executed 0 or more times. Index goes from start to end-1 inclusive. If end = start, loop is not executed.
?leave	( flag -- )	Exit from a doloop if flag is non-zero.
do	( end start -- )	Begin a doloop. Index goes from start to end-1 inclusive. Example: 10 0 do i . loop (prints 0 1 2...d e f).
i	( -- n )	Leaves the loop index on the stack.
j	( -- n )	Leaves the loop index of the next outer enclosing loop on the stack.
leave	( -- )	Exit from doloop.
loop	( -- )	End of doloop.

The following screen shows several examples of how loops are used.

---

ok 10 5 do i .  loop 
5 6 7 8 9 a b c d e f
ok
ok 2000 1000 do i .  i c@ . cr   i c@ ff = if leave then  4 +loop 
1000 23
1004 0
1008 fe
100c 0
1010 78
1014 ff
ok : scan ( byte -- ) 
]    6000 5000     (Scan memory 5000 - 6000 for bytes not equal to the specified byte)
]    do dup i c@ <> ( byte error? ) 
]      if i . then  ( byte ) 
]    loop 
]    drop ( the original byte was still on the stack, discard it ) 
]  ; 
ok 55 scan 
5005 5224 5f99 
ok 6000 5000 do i i c! loop     (Fill a region of memory with a stepped pattern)
ok       
ok 500 value testloc 
ok : test16 ( -- ) 1.0000 0 ( do 0-ffff )     (Write different 16-bit values to a location)
]     do i testloc w! testloc w@ i <> ( error? )     (Also check the location)
]       if ." Error - wrote " i . ." read " testloc w@ . cr 
]        leave ( exit after first error found )     (This line is optional)
]       then 
]     loop 
]  ; 
ok test16 
ok 6000 to testloc 
ok test16 
Error - wrote 200 read 300 
ok 

---

Additional Control Commands

Table 4-32 contains descriptions of additional program execution control commands.

Table 4-32 Program Execution Control Commands

Command	Stack Diagram	Description
abort	( -- )	Abort current execution and interpret keyboard commands.
abort" ccc"	( abort? -- )	If abort? is true, abort and display message.
eval	( addr len -- )	Interpret Forth source from addr len.
execute	( xt -- )	Execute the word whose execution token is on the stack.
exit	( -- )	Return from the current word. (Cannot be used in counted loops.)
quit	( -- )	Same as abort, but leave stack intact.

abort causes immediate termination and returns control to the keyboard. abort" is similar to abort but is different in two respects. abort" removes a flag from the stack and only aborts if the flag is true. Also, abort" prints any desired message when the abort takes place.

eval takes a string from the stack (specified as an address and a length). The characters in that string are then interpreted as if they were entered from the keyboard. If a Forth text file has been loaded into memory (see Chapter 5, Loading and Executing Programs), then eval can be used to compile the definitions contained in the file.