!<arch>
a0001.htm/      851311200   500   0     100644  8065      `
<title>ANS Forth RFI 0001: regarding the "flag" returned 
by <a href=dpans11.htm#11.6.1.2090>READ-LINE</a> at end of file</title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>The questions covered herein were raised by query

<p>Q0001, regarding the "flag" returned 
by <a href=dpans11.htm#11.6.1.2090>READ-LINE</a> at end of file boundary
conditions.

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0001 as received</a></h2>

The following query has been assigned number Q0001 and has been
tentatively assigned to Mitch Bradley for drafting a response.
- Greg Bailey, by direction, Tue, 21 Mar 95 12:40:30 PST
<hr>

<pre>
Subject: Request for clarification--READ-LINE
To: x3j14@minerva.com, erather@aol.com
From: lgc@bluemax.jpl.nasa.gov (Loring Craymer)
Date: Mon, 23 Jan 95 09:14:21 -0800
Message-Id: <9501231714.AA00637@bluemax>
Received: from bluemax.jpl.nasa.gov by med3.minerva.com	
; Mon, 23 Jan 1995 
11:00 PST
Content-Type: text
>From lgc Mon Jan 23 09:14:21 0800 1995 remote from bluemax.jpl.nasa.gov
Received: from bluemax (bluemax.jpl.nasa.gov [128.149.53.31]) by 
telerobotics.jpl.nasa.gov (8.6.8/8.6.6) with SMTP id KAA00235; Mon, 23 Jan 
1995 10:57:40 -0800
Received: by bluemax (920110.SGI/911001.SGI) for 
@telerobotics.jpl.nasa.gov:erather@aol.com id AA00637; Mon, 23 Jan 95 09:14:21 
-0800
Content-Length: 1072
</pre>

Dear Elizabeth:

<p>In the course of writing a test suite for the FILE wordset, I've discovered
that the <a href=dpans11.htm#11.6.1.2090>READ-LINE</a> definition is glaringly 
incomplete.  For this reason,
I am submitting this request for clarification (I assume that email is
sufficient; I don't recall that a more formal process is required).


<p>Request for clarification:

<pre>
<a href=dpans11.htm#11.6.1.2090>11.6.1.2090</a> 
READ-LINE 
( c-addr u1 fileid -- u2 flag ior)
</pre>

What is the meaning of "flag"?  The rationale suggests that it is
an end-of-file flag (or not-end-of-file from the behavior documented
in the definition), but this is not clear from the definition.

<p>What happens if the end of the file is encountered while reading a
line?  The definition states that "If the operation succeeded, flag
is true and ior is zero", but success is not defined.  I assume that
success is either that u1 characters were read or that a line terminator
was encountered.

<p>Suggested resolution:  flag is true unless the end-of-file is encountered,
in which case it is false.  ior does not reflect whether the
end-of-file was encountered or not.

<p>
--Loring


<h2><a name="reply">TC Reply to Q0001</a></h2>
<pre>
From: Erather@aol.com
Subject: Official Response to Q0001
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Fri, 31 Mar 95 12:51:59 PST  
Doc#:  X3J14/Q0001R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  March 31, 1995
Title: Response to Request for Interpretation Q0001, Clarification of
READ-LINE
</pre>

Q0001 DRAFT rev 1

<hr>
Key

<i><blockquote>
Indicates lines from the original inquiry.  The entirty text of the
inquiry is cited in this way.
</blockquote></i>

<b><blockquote>
Indicates excerpts from the standard
</blockquote></b>

Unmarked lines comprise the response to the inquiry.
<hr>

<i><blockquote>
Request for clarification:

<pre>
<a href=dpans11.htm#11.6.1.2090>11.6.1.2090</a> 
READ-LINE 
( c-addr u1 fileid -- u2 flag ior)
</pre> 

What is the meaning of "flag"?  The rationale suggests that it is
an end-of-file flag (or not-end-of-file from the behavior documented
in the definition), but this is not clear from the definition.
</blockquote></i>

In the following excerpt from the definition of 
<a href=dpans11.htm#11.6.1.2090>READ-LINE</a> 
, the word "if"
means "If and only if".

<b><blockquote>
If the operation is initiated when the value returned by 
<a href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>
is equal to the value returned by 
<a href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> for the file identified
by fileid, flag is false ...
</blockquote></b>



<i><blockquote>
What happens if the end of the file is encountered while reading a
line?  The definition states that "If the operation succeeded, flag
is true and ior is zero", but success is not defined.  I assume that
success is either that u1 characters were read or that a line terminator
was encountered.
</blockquote></i>

"success" means that one of the following situations occurred:

<ol>
<li>Some non-terminator characters were read into the buffer or

<li>A line with a valid terminator sequence, but no characters other
than the terminator sequence, was read.  In this case, u2=0,
flag=true, and ior=zero.
</ol>

Specifically, if the last line in the file is non-empty, but has no
terminator, an attempt to read that line will "succeed", returning the
number of characters thus read, and flag will be true.  The next
read, assuming that no intervening 
<a href=dpans11.htm#11.6.1.2142>REPOSITION-FILE</a> occurs, will return
u2=0, flag=false, ior=false.

<p>Here is complete list of return value combinations and their meanings:

<pre>
u2	flag	ior	Meaning
--	----	---	-------
X	X	nonzero	Something bad and unexpected happened
			(end-of-file is not "unexpected")

0	false	zero	End-of-file; no characters were read

0	true	zero	A blank line was read

0&lt;u2&lt;u1	true	zero	The entire line was read

u1	true	zero	A partial line was read; the rest would
			not fit in the buffer, and can be acquired
			by additional calls to <a href=dpans11.htm#11.6.1.2090>READ-LINE</a>.
</pre>

<i><blockquote>
Suggested resolution:  flag is true unless the end-of-file is encountered,
in which case it is false.  ior does not reflect whether the
end-of-file was encountered or not.
</blockquote></i>

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
From: Erather@aol.com
Subject: Letter Ballot 012
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Fri, 31 Mar 95 12:54:23 PST  
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14  Project:
 X3J14, ANS Forth
Doc#:  X3J14/LB012
Reference Doc#s:  X3J14/Q0001R, X3.215.1994 ANS Forth
Date:  March 31, 1995
Title: Response to Request for Interpretation Q0001
Ballot Period:  30 Days
Ballot Closes NOON DATE:  April 30, 1995
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130

Statement:
    Document X3J14/Q0001R contains a proposed Response to Request for
    Interpretation Q0001.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?

YES____ NO____ ABSTAIN____  [NO or ABSTAIN votes require an explanation]

Signature:  [not required for email ballots]
Name:
Organization:

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail or fax to me at the above address,
before the closing date & time.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
From: Erather@aol.com
Subject: Letter Ballot Results
To: X3J14 Technical Committee
Date: Fri, 05 May 95 18:50:18 PDT  
Letter ballots 12 [and 13] have closed.  Both passed.  Results follow.

Letter ballot 12:  13 yes, 0 no, 0 abstaining.

[irrelevant material deleted]

Thank you all for your participation.  Of the 14 votes received, 9 came by
email, and the rest by fax (plus mine!).

Regards...
Elizabeth
</pre>

a0002.htm/      851312700   500   0     100644  17319     `
<title>ANS Forth RFI 0002: search orders in which a given wordlist
occurs more than once</title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>The questions covered herein were raised by query

<p>Q0002, regarding the significance of defining search orders in
which a given wordlist occurs more than once.

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0002 as received</a></h2>

The following query has been assigned number Q0002 and has been
tentatively assigned to Mitch Bradley for drafting a response.
- Greg Bailey, by direction, Tue, 21 Mar 95 12:44:17 PST
<hr>

<pre>
Subject: request for interpretation
To: x3j14@minerva.com
Cc: beebeebee@aol.com
From: John Rible <jrible@cruzio.com>
Date: Fri, 17 Mar 1995 01:46:52 -0800
Message-Id: <199503170944.BAA21566@mail3.netcom.com>
Received: from cruzio.com by med3.minerva.com	; Fri, 17 Mar 1995 01:48 PST
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
>From jrible Fri Mar 17 01:46:52 0800 1995 remote from cruzio.com
Received: from cruzio.com by mail3.netcom.com (8.6.10/Netcom) id BAA21566; 
Fri, 17 Mar 1995 01:44:27 -0800
Received: from cruzio38.cruzio.com by cruzio.cruzio.com id aa29048; 17 Mar 95 
1:40 PST
X-Sender: jrible@cruzio.com
X-Mailer: <PC Eudora Version 1.4>
Content-Length: 2656
</pre>

folks-

<p>
A friend has implemented wordlists using a linked-list to maintain the search 
order. He put two links in each wordlist structure, one for a static list of 
wordlists, the other a dynamic link for the search order. This avoided having 
to allocate an arbitrary amount of space for the search order list/stack.

<p>
After arguing with him that this is not compliant with the standard, I can't 
find anything explicit that backs me up. The problem with his method is that 
each wordlist can only appear ONCE in the search order. Well, that's not a 
problem in itself, but when a wordlist already in the search order is added 
to the top its previous location is lost! Again, that's not a real problem if 
the complete search order is always set explicitly, since the deeper 
occurrance 
will never produce a match.

<p>
But it sure messes up partial search order changes, such as using <a href=dpans16.htm#16.6.2.0715>ALSO</a> or 
<a href=dpans16.htm#16.6.2.2037>PREVIOUS</a> to temporarily change the order. For example, the following sequence 
will hang his system:

<pre>
<a href=dpans16.htm#16.6.2.1965>ONLY</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a>
VOCABULARY HIDDEN
...
<a href=dpans16.htm#16.6.2.0715>ALSO</a> HIDDEN <a href=dpans16.htm#16.6.2.0715>ALSO</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a>  <a href=dpans6.htm#6.2.2535>\</a> so FORTH is searched first
...
<a href=dpans16.htm#16.6.2.2037>PREVIOUS</a>                <a href=dpans6.htm#6.2.2535>\</a> FORTH is no longer in the search order!!!
</pre>

The requirement that I can't find, but believe that we intended, based on 
extensive common practice, would require the phrase   set-order get-order  to 
have no effect on the stack (as long as set-order got valid arguments, 
anyway). 
The problem sure seemed obvious to me, but he doesn't think it is, and even 
came 
up with the following definitions to deal with the issue: 

<pre>
<a href=dpans6.htm#6.1.0070>'</a> <a href=dpans6.htm#6.2.1930>NIP</a>  <a href=dpans6.htm#6.2.2405>VALUE</a> 'ALSO

<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.0715>ALSO</a> <a href=dpans6.htm#6.1.0080>(</a> - ) <a href=dpans6.htm#6.1.2510>[']</a> <a href=dpans6.htm#6.1.0290>1+</a>  <a href=dpans6.htm#6.2.2295>TO</a> 'ALSO <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.1965>ONLY</a> <a href=dpans6.htm#6.1.0080>(</a> - ) -1 <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>  <a href=dpans6.htm#6.1.2510>[']</a> <a href=dpans6.htm#6.2.1930>NIP</a>  <a href=dpans6.htm#6.2.2295>TO</a> 'ALSO <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.2037>PREVIOUS</a> <a href=dpans6.htm#6.1.0080>(</a> - ) <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a>  <a href=dpans6.htm#6.2.1930>NIP</a> <a href=dpans6.htm#6.1.0300>1-</a>  <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> <VOCABULARY> <a href=dpans6.htm#6.1.0080>(</a> wid - ) <a href=dpans6.htm#6.2.2535>\</a> wid is the address of the wordlist data structure
   <a href=dpans6.htm#6.1.0580>>R</a> <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a>  'ALSO <a href=dpans6.htm#6.1.1370>EXECUTE</a>  <a href=dpans6.htm#6.1.2060>R></a> <a href=dpans6.htm#6.1.2260>SWAP</a>  <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>  <a href=dpans6.htm#6.1.2510>[']</a> <a href=dpans6.htm#6.2.1930>NIP</a>  <a href=dpans6.htm#6.2.2295>TO</a> 'ALSO <a href=dpans6.htm#6.1.0460>;</a>

<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a> <a href=dpans6.htm#6.1.0080>(</a> - ) <a href=dpans16.htm#16.6.1.1595>FORTH-WORDLIST</a> <VOCABULARY> <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> VOCABULARY <a href=dpans6.htm#6.1.0080>(</a> 'name' - )  <a href=dpans6.htm#6.1.1000>CREATE</a>  ...  <a href=dpans6.htm#6.1.1250>DOES></a> <VOCABULARY> <a href=dpans6.htm#6.1.0460>;</a>
</pre>

<p>
While these deal with some of the situations of adding and removing 
search-order 
entries, I've seen a lot of places (in Sun's OpenBoot, for example) where 
existing code would go up in flames if temporarily adding and removing a 
vocabulary that happened to already be in the search order took it out 
completely, as in my example above. Of course, the pathological (but currently 
working)  <a href=dpans16.htm#16.6.2.1965>ONLY</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a> <a href=dpans16.htm#16.6.2.0715>ALSO</a> <a href=dpans16.htm#16.6.2.2037>PREVIOUS</a>  also leaves his search order empty.

<p>
Thanks for your responses (even the "you're a *&^#@*$%# idiot for wasting my 
time" ones add a data point!-)

<pre>
John Rible  QuickSand  "hardware, software, and so forth"  jrible@cruzio.com
            317 California Street, Santa Cruz, CA  95060-4215   408-458-0399
</pre>

<h2><a name="reply">TC Reply to Q0002</a></h2>

<pre>
From: Erather@aol.com
Subject: Official Response to Q0002
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Fri, 31 Mar 95 12:52:24 PST  
Doc#:  X3J14/Q0002R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  March 31, 1995
Title: Response to Request for Interpretation Q0002, Clarification of Search
Orders
</pre>

Q0002 DRAFT rev 1

<hr>
Key

<i><blockquote>
Indicates lines from the original inquiry.  The entiry text of the
inquiry is cited in this way.
</blockquote></i>

<b><blockquote>
Indicates excerpts from the standard
</blockquote></b>

Unmarked lines comprise the response to the inquiry.
<hr>

<i><blockquote>
A friend has implemented wordlists using a linked-list to maintain
the search order. He put two links in each wordlist structure, one for
a static list of wordlists, the other a dynamic link for the search
order. This avoided having to allocate an arbitrary amount of space
for the search order list/stack.

<p>
After arguing with him that this is not compliant with the standard, I
can't find anything explicit that backs me up. The problem with his
method is that each wordlist can only appear ONCE in the search
order. Well, that's not a problem in itself, but when a wordlist
already in the search order is added to the top its previous location
is lost! Again, that's not a real problem if the complete search order
is always set explicitly, since the deeper occurrance will never
produce a match.
</blockquote></i>

In the following excerpt from the definition of <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>, the phrase
"word lists" means "sequence of word lists".

<b><blockquote>
      Set the search order to the word lists identified by widn ... wid1.
      Subsequently, ...
</blockquote></b>

<a href=dpans16.htm#16.6.1.1647>GET-ORDER</a> must return exactly the same sequence of wids "widn .. wid1" that
appeared in the arguments to the most recent execution of <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>, even
if a particular word list identifier appears more than once in that sequence.

<p>
A Standard System is permitted to optimize its searching process so that
the existence of repetetions in the search order need not result in redundant
searches, but if so (a) the behavior of <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a> and <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> must be as
described in the preceding paragraph, and (b) the results of a search must
be indistinguishable in all cases from the results were there no such
optimizations.

<i><blockquote>
But it sure messes up partial search order changes, such as using <a href=dpans16.htm#16.6.2.0715>ALSO</a>
or <a href=dpans16.htm#16.6.2.2037>PREVIOUS</a> to temporarily change the order. For example, the
following sequence will hang his system:

<pre>
<a href=dpans16.htm#16.6.2.1965>ONLY</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a>
VOCABULARY HIDDEN
...
<a href=dpans16.htm#16.6.2.0715>ALSO</a> HIDDEN <a href=dpans16.htm#16.6.2.0715>ALSO</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a>  <a href=dpans6.htm#6.2.2535>\</a> so <a href=dpans16.htm#16.6.2.1590>FORTH</a> is searched first
...
<a href=dpans16.htm#16.6.2.2037>PREVIOUS</a>                <a href=dpans6.htm#6.2.2535>\</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a> is no longer in the search order!!!
</pre>
</blockquote></i>

Historically, in most implementations of the <a href=dpans16.htm#16.6.2.0715>ALSO</a> .. <a href=dpans16.htm#16.6.2.1965>ONLY</a> search order
mechanism, the sequence shown would result in the search order containing

<pre>
 &lt;minimum search order&gt; &lt;FORTH wordlist&gt; &lt;HIDDEN wordlist&gt;
</pre>

The standard intends to codify that existing practice.


<i><blockquote>
The requirement that I can't find, but believe that we intended, based
on extensive common practice, would require the phrase "set-order get-order"
to have no effect on the stack (as long as set-order got valid arguments,
anyway).  The problem sure seemed obvious to me, but he doesn't think it
is, and even came up with the following definitions to deal with the issue:

<pre>
<a href=dpans6.htm#6.1.0070>'</a> <a href=dpans6.htm#6.2.1930>NIP</a>  <a href=dpans6.htm#6.2.2405>VALUE</a> 'ALSO

<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.0715>ALSO</a> <a href=dpans6.htm#6.1.0080>(</a> - ) <a href=dpans6.htm#6.1.2510>[']</a> <a href=dpans6.htm#6.1.0290>1+</a>  <a href=dpans6.htm#6.2.2295>TO</a> 'ALSO <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.1965>ONLY</a> <a href=dpans6.htm#6.1.0080>(</a> - ) -1 <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>  <a href=dpans6.htm#6.1.2510>[']</a> <a href=dpans6.htm#6.2.1930>NIP</a>  <a href=dpans6.htm#6.2.2295>TO</a> 'ALSO <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.2037>PREVIOUS</a> <a href=dpans6.htm#6.1.0080>(</a> - ) <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a>  <a href=dpans6.htm#6.2.1930>NIP</a> <a href=dpans6.htm#6.1.0300>1-</a>  <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> <VOCABULARY> <a href=dpans6.htm#6.1.0080>(</a> wid - ) <a href=dpans6.htm#6.2.2535>\</a> wid is the address of the wordlist data structure
   <a href=dpans6.htm#6.1.0580>>R</a> <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a>  'ALSO <a href=dpans6.htm#6.1.1370>EXECUTE</a>  <a href=dpans6.htm#6.1.2060>R></a> <a href=dpans6.htm#6.1.2260>SWAP</a>  <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>  <a href=dpans6.htm#6.1.2510>[']</a> <a href=dpans6.htm#6.2.1930>NIP</a>  <a href=dpans6.htm#6.2.2295>TO</a> 'ALSO <a href=dpans6.htm#6.1.0460>;</a>

<a href=dpans6.htm#6.1.0450>:</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a> <a href=dpans6.htm#6.1.0080>(</a> - ) <a href=dpans16.htm#16.6.1.1595>FORTH-WORDLIST</a> <VOCABULARY> <a href=dpans6.htm#6.1.0460>;</a>
<a href=dpans6.htm#6.1.0450>:</a> VOCABULARY <a href=dpans6.htm#6.1.0080>(</a> 'name' - )  <a href=dpans6.htm#6.1.1000>CREATE</a>  ...  <a href=dpans6.htm#6.1.1250>DOES></a> <VOCABULARY> <a href=dpans6.htm#6.1.0460>;</a>
</pre>
</blockquote></i>

With these definitions, the sequence "ALSO GET-ORDER" would not yield the
result specified by the standard.

<i><blockquote>
While these deal with some of the situations of adding and removing 
search-order entries, I've seen a lot of places (in Sun's OpenBoot,
for example) where existing code would go up in flames if temporarily
adding and removing a vocabulary that happened to already be in the
search order took it out completely, as in my example above. Of course,
the pathological (but currently working)  <a href=dpans16.htm#16.6.2.1965>ONLY</a> <a href=dpans16.htm#16.6.2.1590>FORTH</a> <a href=dpans16.htm#16.6.2.0715>ALSO</a> <a href=dpans16.htm#16.6.2.2037>PREVIOUS</a>  also
leaves his search order empty.
</blockquote></i>

The ANS Forth search order wordset is intended to provide a predictable
mechanism for managing search orders in arbitrary ways, albeit subject to
the system-dependent limitation on the maximum number of word lists.  Some
applications, for example, choose to use the search order as a "stack",
adding and removing word lists without regard to whether or not those
word lists already appear in the search order.

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
From: Erather@aol.com
Subject: Letter Ballot 013
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Fri, 31 Mar 95 12:54:18 PST  
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14  Project:
 X3J14, ANS Forth
Doc#:  X3J14/LB013
Reference Doc#s:  X3J14/Q0002R, X3.215.1994 ANS Forth
Date:  March 31, 1995
Title: Response to Request for Interpretation Q0002
Ballot Period:  30 Days
Ballot Closes NOON DATE:  April 30, 1995
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130

Statement:
    Document X3J14/Q0002R contains a proposed Response to Request for
    Interpretation Q0002.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?

YES____ NO____ ABSTAIN____  [NO or ABSTAIN votes require an explanation]

Signature:  [not required for email ballots]
Name:
Organization:

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail or fax to me at the above address,
before the closing date & time.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
From: Erather@aol.com
Subject: Letter Ballot Results
To: X3J14 Technical Committee
Date: Fri, 05 May 95 18:50:18 PDT  
Letter ballots [12 and] 13 have closed.  Both passed.  Results follow.

[...]

Letter ballot 13:  13 yes, 1 no, 0 abstaining.

[...]

Jax [Jack Woehr] voted No on LB13.  His comments follow:

LB13, Woehr: I made a proposal which was drowned out in Mitch's discus-
sion with himself on the maillist. It was letting Mitch make all the
decisions in consultation with himself that got us in trouble at the
spring meeting in Oregon in 1992 and delayed the standard by about a
year. I expect my proposals to be heard, even if not adopted, in hopes
we can avoid similar problems in the future.

---------  FOR THE RECORD  -----------------------------------
[Here is the e-mail message to which Woehr refers.  The active
part of the discussion occurred over a three day period, involved
about a dozen e-mail messages, and had seven participants who
posted.]

>
> > I think Mitch has gotten the issue here backward.

<...>

>   the arguments that it passes to <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> be mutually distinct?
>
> I believe that the answer is emphatically "no".


 I agree with Mitch whole-heartedly. I would move to add that:

"It is the sense of the X3J14 TC that no element of <a href=dpans17.htm#17.6.1.2191>SEARCH</a> <a href=dpans16.htm#16.6.2.1985>ORDER</a> Wordset
introduces novelty into general Forth praxis, with the exception
that a <a href=dpans16.htm#16.6.1.2460>WORDLIST</a> now has a tangible representation on the stack, whereas
FORTH-83 VOCABULARY had no such tangible representation. In all other
respects the de-facto behavior of Forth search order operations are
utterly unchanged from Forth-83."

 Do I hear a second?

  =jax=

[...]

Thank you all for your participation.  Of the 14 votes received, 9 came by
email, and the rest by fax (plus mine!).

Regards...
Elizabeth
</pre>

a0003.htm/      851313180   500   0     100644  21650     `
<title>ANS Forth RFI 0003: What's allowed between <a href=dpans6.htm#6.1.1000>CREATE</a> and DOES></title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>
The questions covered herein were raised by query

<p>
Q0003, regarding usage rules for defining words centering on various
wordlist actions occurring between <a href=dpans6.htm#6.1.1000>CREATE</a> and <a href=dpans6.htm#6.1.1250>DOES></a>.

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0003 as received</a></h2>

The following query has been assigned number Q0003 and has been
tentatively assigned to Jack Woehr for drafting a response.
- Greg Bailey, by direction  950509 1900Z
<hr>

<pre>
Subject: Defining words, search order and wordlists.
To: ANSForth@minerva.com
From: aph@oclc.org (Andrew Houghton)
Date: Tue, 9 May 95 11:09:48 -0400
Message-Id: <9505091520.AA26898@fssun09.dev.oclc.org>
Received: from oclc.org by med3.minerva.com ; Tue,  9 May 1995 08:25 PDT
Content-Type: text
>From aph Tue May  9 11:09:48 0400 1995 remote from oclc.org
Return-Path: <aph@oclc.org>
Received: from next30-06 (next30-06.dev.oclc.org) by fssun09.dev.oclc.org
  (4.1/SMI-4.1) id AA26898; Tue, 9 May 95 11:20:56 EDT
Received: by next30-06 (NX5.67d/NX3.0X) id AA00583; Tue, 9 May 95 11:09:48 -0400
Received: by NeXT.Mailer (1.100)
Received: by NeXT Mailer (1.100)
Content-Length: 7015
</pre>

I'm not sure whether doing the following is legal ANS FORTH so I was
looking for someone to provide an interpretation as to whether it is
legal and if not why not.

<p>
Here is my problem.  Define the following:

<pre>
  \ Add selx to search order and make new definitions go into selx.
: set-current-wordlist  ( selx -- )
  >r get-order 1+ r> swap set-order definitions ;

  \ Fill wordlist with default definitions.
: fill-wordlist  ( n n n -- )
  s" constant a" evaluate
  s" constant b" evaluate
  s" constant c" evaluate ;

  \ Create new wordlist with default definitions.
: create-wordlist  ( -- )
  create
    wordlist set-current-wordlist
    1 2 3 fill-wordlist
  does>            ( body -- )
    set-current-wordlist ;
  

  \ Create new wordlist with default definitions, revised.
: create-wl  ( -- )
  wordlist dup set-current-wordlist
  1 2 3 fill-wordlist
  previous definitions
  create
    dup , set-current-wordlist
  does>      ( body -- )
    @ set-current-wordlist ;
</pre>

I believe that the above words set-current-wordlist and fill-wordlist by
themselves conform to the standard.  My problem lies with the word
create-wordlist.  Create-wordlist tries to create a defining word which
creates a wordlist, adds the newly created wordlist to the search order,
set the current definitions to go into the newly created wordlist, then
fills the wordlist with some common definitions.

<p>
When the word create-wordlist is executed (ie. create-wordlist abc) it
produces a new (ie. abc) which PFE, an ANS FORTH, is marked in the
dictionary as a variable -- not a defining word and c in the newly
created wordlist is marked in its dictionary as a defining word -- not
a constant!  As far as I can tell from the standard, this could be a
result of does> (section 6.1.1250) replacing the execution semantics of
the most recent definition, ie. abc which was defined by create, and the
fact that fill-wordlist creates new definitions.  It seems that section
"3.4.5 Compilation" of the standard may apply somehow as well.

<p>
The standard seems unclear to me when it says that: "does> replaces the
execution semantics of the most recent definition."  I would have expected
it to use the term "current definition" from "2.1 Definitions of terms."
But again whether its "recent definition" or "current definition" it really
says to me: "replaces the execution semantics of the most recent/current
definition [in the most recent/current definition's wordlist]".  Note I
added the bracketed item to show what the standard implies to me.  However
it is clear that PFE, an ANS FORTH, implies "in the current wordlist where
definitions are being placed."

<p>
It's unclear in the standard, to me, which one is correct.  Given the
ambiguity I rewrote the word create-wordlist and it appears as the word
create-wl.  The new word create-wl now creates the wordlist fills it with
the common definitions and restores the previous wordlist.  Then create-wl 
*creates* the defining word.  This seems to work for PFE but may not work
for other ANS implementations.  However, this points out another possible
problem with the definitions of create-wordlist and create-wl.

<p>
The newly perceived problem is that both words change the search order before
the does> is done.  It seems to me that sections <a href=dpans16.htm#16.3.3>16.3.3</a> and <a href=dpansa16.htm#A.16.3.3>A.16.3.3</a> say that
this produces an ambiguous condition.  Is this correct?  Does <a href=dpans16.htm#16.3.3>16.3.3</a> refer
to when the word create-wordlist is being compiled or the word being defined
by create-wordlist?

<p>
My final question is: "Is it possible to portably create a defining word
which creates a wordlist, fills that wordlist with definitions and then
switches the search order to that wordlist with the current ANS standard?"

<hr>
The following sections from the ANS standard, which I thought were
relevant to the problem, are quoted below for your convience:

<blockquote>
<a href=dpans2.htm#2.1>2.1</a> Definitions of terms 

<dl>

<dt>
ambiguous condition: 

<dd>
  A circumstance for which this Standard does not prescribe a specific
  behavior for Forth systems and programs. 

<p>
  Ambiguous conditions include such things as the absence of a needed
  delimiter while parsing, attempted access to a nonexistent file, or
  attempted use of a nonexistent word. An ambiguous condition also exists
  when a Standard word is passed values that are improper or out of range. 

<dt>
current definition: 

<dd>
  The definition whose compilation has been started but not yet ended. 

<dt>
defining word: 

<dd>
  A Forth word that creates a new definition when executed. 

<dt>
definition: 

<dd>
  A Forth execution procedure compiled into the dictionary. 

<dt>
dictionary: 

<dd>
  An extensible structure that contains definitions and associated
  data space. 
</dl>


<a href=dpans3.htm#3.4.5>3.4.5</a> Compilation 

<p>
A program shall not attempt to nest compilation of definitions. 

<p>
During the compilation of the current definition, a program shall
not execute any defining word, <a href=dpans6.htm#6.2.0455>:NONAME</a>, or any definition that
allocates dictionary data space. The compilation of the current
definition may be suspended using <a href=dpans6.htm#6.1.2500>[</a> (left-bracket) and resumed
using <a href=dpans6.htm#6.1.2540>]</a> (right-bracket). While the compilation of the current
definition is suspended, a program shall not execute any defining
word, <a href=dpans6.htm#6.2.0455>:NONAME</a>, or any definition that allocates dictionary data space. 

<p>
<a href=dpans6.htm#6.1.1250>6.1.1250</a>  <a href=dpans6.htm#6.1.1250>DOES></a> does CORE 

<p>
Interpretation: Interpretation semantics for this word are undefined. 

<p>
Compilation: ( C: colon-sys1 -- colon-sys2 ) 

<p>
Append the run-time semantics below to the current definition. Whether
or not the current definition is rendered findable in the dictionary by
the compilation of <a href=dpans6.htm#6.1.1250>DOES></a> is implementation defined. Consume colon-sys1
and produce colon-sys2. Append the initiation semantics given below to
the current definition. 

<p>
Run-time: ( -- ) ( R: nest-sys1 -- ) 

<p>
Replace the execution semantics of the most recent definition, referred
to as name, with the name execution semantics given below. Return control
to the calling definition specified by nest-sys1. An ambiguous condition
exists if name was not defined with <a href=dpans6.htm#6.1.1000>CREATE</a> or a user-defined word that
calls <a href=dpans6.htm#6.1.1000>CREATE</a>. 

<p>
Initiation: ( i*x -- i*x a-addr ) ( R: -- nest-sys2 ) 

<p>
Save implementation-dependent information nest-sys2 about the calling
definition. Place name's data field address on the stack. The stack
effects i*x represent arguments to name. 

<p>
name Execution: ( i*x -- j*x ) 

<p>
Execute the portion of the definition that begins with the initiation
semantics appended by the <a href=dpans6.htm#6.1.1250>DOES></a> which modified name. The stack effects
i*x and j*x represent arguments to and results from name, respectively. 


<p>
<a href=dpans16.htm#16.3.3>16.3.3</a> Finding definition names 

<p>
An ambiguous condition exists if a program changes the compilation word
list during the compilation of a definition or before modification of the
behavior of the most recently compiled definition with <a href=dpans15.htm#15.6.2.0470>;CODE</a>, <a href=dpans6.htm#6.1.1250>DOES></a>, or
<a href=dpans6.htm#6.1.1710>IMMEDIATE</a>. 


<p>
<a href=dpansa16.htm#A.16.3.3>A.16.3.3</a> Finding definition names 

<p>
In other words, the following is not guaranteed to work: 

<pre>
<a href=dpans6.htm#6.1.0450>:</a> FOO  ... <a href=dpans6.htm#6.1.2500>[</a> ... <a href=dpans16.htm#16.6.1.2195>SET-CURRENT</a> <a href=dpans6.htm#6.1.2540>]</a> ... <a href=dpans6.htm#6.1.2120>RECURSE</a> ... <a href=dpans6.htm#6.1.0460>;</a>  <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>
</pre>

<p>
<a href=dpans6.htm#6.1.2120>RECURSE</a>, <a href=dpans6.htm#6.1.0460>;</a> (semicolon), and <a href=dpans6.htm#6.1.1710>IMMEDIATE</a> may or may not need information
stored in the compilation word list. 

</blockquote>

<h2><a name="reply">TC Reply to Q0003</a></h2>
<pre>
From: Elizabeth D. Rather
Subject: Q0003R, Wordlists, Official Response
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Wed, 31 May 95 17:03:44 PDT  
Doc#:  X3J14/Q0003R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  May 16, 1995
Title: Response to Request for Interpretation Q0003, Clarification of Wordlists
</pre>

Abstract: No definition can be added to the dictionary between <a href=dpans6.htm#6.1.1000>CREATE</a> and
<a href=dpans6.htm#6.1.1250>DOES></a>.  Changing compilation wordlist between <a href=dpans6.htm#6.1.1000>CREATE</a> and <a href=dpans6.htm#6.1.1250>DOES></a> is
ambiguous.

<pre>
X3.215-1994_KEYWORD_LIST:
        Core Word Set
        <a href=dpans6.htm#6.1.1000>CREATE</a> <a href=dpans6.htm#6.1.1000>6.1.1000</a> <a href=dpans6.htm#6.1.1250>DOES></a> <a href=dpans6.htm#6.1.1250>6.1.1250</a>
        Search Order Word Set
        <a href=dpans16.htm#16.6.1.1180>DEFINITIONS</a> <a href=dpans16.htm#16.6.1.1180>16.6.1.1180</a> <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a> <a href=dpans16.htm#16.6.1.1647>16.6.1.1647</a> <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> <a href=dpans16.htm#16.6.1.2197>16.6.1.2197</a>
        Terms:
                Ambiguous condition <a href=dpans2.htm#2.1>2.1</a>
                Compilation word list <a href=dpans16.htm#16.6.1.2195>16.6.1.2195</a>
X3.215-1994_KEYWORD_LIST;
Author: Jack Woehr
</pre>

<i><blockquote>
Here is my problem.  Define the following:

<pre>
  \ Add selx to search order and make new definitions go into selx.
: set-current-wordlist  ( selx -- )
  >r get-order 1+ r> swap set-order definitions ;
</pre>
</blockquote></i>

        set-current-wordlist is standard Forth in the given context,
i.e. as a definition commenced while the system is interpretive
mode. Note that it has a dependency on the SEARCH-ORDER Word Set with
Extensions.

<p>
        Incidentally, the Technical Committee encourages the use of
uppercase for Standard words in clarification queries submitted to
X3J14.

<i><blockquote>
<pre>
  \ Fill wordlist with default definitions.
: fill-wordlist  ( n n n -- )
  s" constant a" evaluate
  s" constant b" evaluate
  s" constant c" evaluate ;
</pre>
</blockquote></i>

        fill-wordlist is standard Forth in the given context.

<i><blockquote>
<pre>
  \ Create new wordlist with default definitions.
: create-wordlist  ( -- )
  create
    wordlist set-current-wordlist
    1 2 3 fill-wordlist
  does>            ( body -- )
    set-current-wordlist ;
</pre>
</blockquote></i>

        This definition of create-wordlist is erroneous as later
noted by its author: the wordlist-id is not preserved so that
the body address returned by words can be dereferenced to
the (should have been) stored wordlist-id for set-current wordlist.

<p>
        But this flaw conceals the definition's intent, to effect
<a href=dpans6.htm#6.1.1000>CREATE</a>, change the compilation wordlist, add definitions, then return
to the original compilation wordlist and effect <a href=dpans6.htm#6.1.1250>DOES></a>. This is not
Standard Forth.

<p>
         Words cannot be added to the dictionary between the action of
<a href=dpans6.htm#6.1.1250>DOES></a> and the most recent action of <a href=dpans6.htm#6.1.1000>CREATE</a>. <a href=dpans6.htm#6.1.1250>DOES></a> modifies a word
created by <a href=dpans6.htm#6.1.1000>CREATE</a>. <a href=dpans6.htm#6.1.1250>DOES></a> modifies the most recent definition. Thus
there can have been no new definition added to the dictionary which
was not created by <a href=dpans6.htm#6.1.1000>CREATE</a> immediately prior to a <a href=dpans6.htm#6.1.1250>DOES></a>. Note that
<a href=dpans6.htm#6.1.1250>DOES></a> is found in the Core word set and never modified later in the
Standard when the concept of multiple compilation wordlists is
introduced.

<p>
        Although the Standard does not preclude implementations using
multiple wordlists from having "most recent" definitions in each
wordset, the definition of <a href=dpans6.htm#6.1.1250>DOES></a> is not extended to provide for
multiple wordlists, and makes no provision for other than a single
"most recent" definition.  The clear intent of the Standard is that
words cannot be added to the dictionary between the action of <a href=dpans6.htm#6.1.1250>DOES></a>
and the most recent action of <a href=dpans6.htm#6.1.1000>CREATE</a>.

<p>
        (Also note that the execution of <a href=dpans16.htm#16.6.1.2460>WORDLIST</a> may consume data
space, altering the address returned by <a href=dpans6.htm#6.1.1650>HERE</a>. The portable program
must avoid executing <a href=dpans16.htm#16.6.1.2460>WORDLIST</a> between <a href=dpans6.htm#6.1.1000>CREATE</a> and the execution of
 <a href=dpans6.htm#6.1.0150>,</a> "comma" that saves the wordlist ID in the body of the created
definition. Otherwise, the CREATE'd, DOES>'d entity at runtime will
point at space which subsequently might have been used for the
WORDLIST.)

<p>
        The following was suggested as an improvement the the original
definition of create-wordlist.

<i><blockquote>
<pre>
  \ Create new wordlist with default definitions, revised.
: create-wl  ( name< > -- )
  wordlist dup set-current-wordlist
  1 2 3 fill-wordlist
  previous definitions
  create
    dup , set-current-wordlist
  does>      ( body -- )
    @ set-current-wordlist ;
</pre>
</blockquote></i>

<p>
        This definition create-wl at runtime changes the compilation
wordlist [16.6.1.2195] between <a href=dpans6.htm#6.1.1000>CREATE</a> [6.1.1000] and <a href=dpans6.htm#6.1.1250>DOES></a> [6.1.1250].
The Forth Standard, <a href=dpans16.htm#16.3.3>16.3.3</a> para 4:

<p>
"An ambiguous condition exists if a program changes the compilation
word list during the compilation of a definition or before modi-
fication of the behavior of the most recently compiled definition
with <a href=dpans15.htm#15.6.2.0470>;CODE</a> <a href=dpans6.htm#6.1.1250>DOES></a> or IMMEDIATE."

<p>
        Therefore, while not "non-Standard", the amended definition
create-wl exhibits a platform dependency on the particular resolution
of the ambiguity selected by the hosting Standard System, if create-wl
is to execute deterministically.

<i><blockquote>
My final question is: "Is it possible to portably create a defining word
which creates a wordlist, fills that wordlist with definitions and then
switches the search order to that wordlist with the current ANS standard?"
</blockquote></i>

        Yes.

<pre>
<a href=dpans6.htm#6.1.0450>:</a> SET-CURRENT-WORDLIST <a href=dpans6.htm#6.1.0080>(</a> my_wid --) <a href=dpans6.htm#6.2.2535>\</a> as above
        <a href=dpans6.htm#6.1.0580>>R</a> <a href=dpans16.htm#16.6.1.1647>GET-ORDER</a> <a href=dpans6.htm#6.1.0290>1+</a> <a href=dpans6.htm#6.1.2060>R></a> <a href=dpans6.htm#6.1.0080>(</a> -- widn wid1 n my_wid)
        <a href=dpans6.htm#6.1.2260>SWAP</a> <a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> <a href=dpans16.htm#16.6.1.1180>DEFINITIONS</a> <a href=dpans6.htm#6.1.0080>(</a> --)
<a href=dpans6.htm#6.1.0460>;</a>

<a href=dpans6.htm#6.1.0450>:</a> 78-VOCABULARY <a href=dpans6.htm#6.1.0080>(</a> "name< >" my_wid --)
        <a href=dpans6.htm#6.1.1000>CREATE</a> <a href=dpans6.htm#6.1.0150>,</a>        <a href=dpans6.htm#6.1.0080>(</a> --)
        <a href=dpans6.htm#6.1.1250>DOES></a> <a href=dpans6.htm#6.1.0080>(</a> self  --) <a href=dpans6.htm#6.2.2535>\</a> runtime
                <a href=dpans6.htm#6.1.0650>@</a>       <a href=dpans6.htm#6.1.0080>(</a> -- my_wid)
                SET-CURRENT-WORDLIST    <a href=dpans6.htm#6.1.0080>(</a> --)
<a href=dpans6.htm#6.1.0460>;</a>

<a href=dpans6.htm#6.1.0450>:</a> CREATE-WORDLIST <a href=dpans6.htm#6.1.0080>(</a> "name< >" --)
        <a href=dpans16.htm#16.6.1.2460>WORDLIST</a> <a href=dpans6.htm#6.1.1290>DUP</a> 78-VOCABULARY <a href=dpans6.htm#6.1.0080>(</a> -- wid)
        SET-CURRENT-WORDLIST <a href=dpans6.htm#6.1.0080>(</a> --)
        fill-wordlist <a href=dpans6.htm#6.2.2535>\</a> _vide supra_
        <a href=dpans16.htm#16.6.2.2037>PREVIOUS</a> <a href=dpans16.htm#16.6.1.1180>DEFINITIONS</a>
<a href=dpans6.htm#6.1.0460>;</a>
</pre>

<p>
From the point of view of CREATE-WORDLIST at runtime, 78-VOCABULARY is
atomic. Its work is done before the change in search order occurs for
the first time. Good factoring avoids a grey area of the Standard.

<p>
        Greg Bailey notes that during the mailing list discussion of
this issue, he erroneously posted using <a href=dpans6.htm#6.1.2410>VARIABLE</a> where <a href=dpans6.htm#6.1.1000>CREATE</a> was
intended. Greg regrets any confusion thus caused.

<pre>
Elizabeth D. Rather             "Forth-based products and
FORTH, Inc.                      Services for real-time
111 N. Sepulveda Blvd. #300      applications since 1973"
Manhattan Beach, CA  90266
(800) 55FORTH or (310) 372-8493
FAX (310) 318-7130
</pre>

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
From: Elizabeth D. Rather
Subject: LB014, RE Q0003, Wordlists
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Wed, 31 May 95 17:03:36 PDT  
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14
Project: X3J14, ANS Forth
Doc#:  X3J14/LB014
Reference Doc#s:  X3J14/Q0003R, X3.215.1994 ANS Forth
Date:  May 31, 1995
Title: Response to Request for Interpretation Q0003, Wordlists
Ballot Period:  30 Days
Ballot Closes NOON DATE:  June 30, 1995
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130
             erather@forth.com

Statement:
    Document X3J14/Q0003R contains a proposed Response to Request for
    Interpretation Q0003.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?


/------------------------  begin response area----------------------\
|
|  YES____ NO____ ABSTAIN____
|
|  Signature:  [not required for email ballots]
|  Name:
|  Organization:
|
|  Explanation (REQUIRED for NO or ABSTAIN votes):
|    <none>
\------------------------  end response area  ----------------------/

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail, fax or email to me at the above
address, before the closing date & time.

   If replying electronically PLEASE edit only within the response area
   indicated above, inserting any explanatory text in place of <none>.
   Any changes made outside that area will likely be overlooked.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14

Elizabeth D. Rather             "Forth-based products and
FORTH, Inc.                      Services for real-time
111 N. Sepulveda Blvd. #300      applications since 1973"
Manhattan Beach, CA  90266
(800) 55FORTH or (310) 372-8493
FAX (310) 318-7130
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
From: Elizabeth D. Rather
Subject: LBs 14 & 15
To: X3J14 Technical Committee
Cc: l.barra@itic.nw.dc.us
Date: Fri, 07 Jul 95 12:05:04 PDT  
Letter ballots 14 [and 15] closed at noon July 1 with the following results:

        Y  N  A NV
LB14:  12, 0, 0, 3

[...]

Thank you for your participation.

Regards,
Elizabeth D. Rather, Chair X3J14

Elizabeth D. Rather             "Forth-based products and
FORTH, Inc.                      Services for real-time
111 N. Sepulveda Blvd. #300      applications since 1973"
Manhattan Beach, CA  90266
(800) 55FORTH or (310) 372-8493
FAX (310) 318-7130
</pre>
a0004.htm/      850764960   500   0     100644  11872     `
<title>ANS Forth RFI 0004: standard punctuation for double-cell numbers</title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>The questions covered herein were raised by query

<p>Q0004, regarding standard punctuation for double-cell numbers when
occurring in programs.

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0004 as received</a></h2>
The following query has been assigned number Q0004 and has been
tentatively assigned to John Hayes for drafting a response.
- Greg Bailey, by direction  950516 0400Z
<hr>

<pre>
Subject: ANS Forth Clarification Procedures
To: greg@minerva.com
From: BiMu@aol.com (Bill Muench)
Date: Mon, 15 May 1995 15:13:21 -0400
Message-Id: <950515151319_119428296@aol.com>
Received: from aol.com by med3.minerva.com <a href=dpans6.htm#6.1.0460>;</a> Mon, 15 May 1995 12:18 PDT
Request for Clairification.
</pre>

I have found the following references to *Text interpreter input number
conversion*.

<p>
The input of Floating-Point numbers is clear, my need for clairification is
with double-cell numbers:

<p>
Will a number with an *embedded* decimal point be converted to a double-cell
number in a Standard Forth system?

<p>
If not, what about <a href=dpansa12.htm#A.12.3.7>A.12.3.7</a> *...should treat numbers that have an embedded
decimal point, but no exponent, as floating-point numbers rather than double
cell numbers. This suggestion, although it has merit, has always been voted
down because it would break too much existing code;* ?

<p>
Is <a href=dpans8.htm#8.3.2>8.3.2</a> an example or the rule? ( a decimal point at the end)

<blockquote>
<a href=dpans8.htm#8.3.2>8.3.2</a> Text interpreter input number conversion

<p>
When the text interpreter processes a number that is immediately followed by
a decimal point and is not found as a definition name, the text interpreter
shall convert it to a double-cell number.
For example, entering <a href=dpans6.htm#6.1.1170>DECIMAL</a> 1234 leaves the single-cell number 1234 on the
stack, and entering <a href=dpans6.htm#6.1.1170>DECIMAL</a> 1234. leaves the double-cell number 1234 0 on the
stack.

<p>
See: <a href=dpans3.htm#3.4.1.3>3.4.1.3</a> Text interpreter input number conversion.

<p>
<a href=dpans12.htm#12.3.7>12.3.7</a> Text interpreter input number conversion

<p>
If the Floating-Point word set is present in the dictionary and the current
base is <a href=dpans6.htm#6.1.1170>DECIMAL</a>, the input number-conversion algorithm shall be extended to
recognize floating-point numbers in this form:

<pre>
Convertible string := &lt;significand&gt;&lt;exponent&gt;
&lt;significand&gt; := [&lt;sign&gt;]&lt;digits&gt;[.&lt;digits0&gt;]
&lt;exponent&gt; := E[&lt;sign&gt;]&lt;digits0&gt;
&lt;sign&gt; := { + | - }
&lt;digits&gt; := &lt;digit&gt;&lt;digits0&gt;
&lt;digits0&gt; := &lt;digit&gt;*
&lt;digit&gt; := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
</pre>

These are examples of valid representations of floating-point numbers in
program source:

<pre>
1E   1.E   1.E0   +1.23E-1   -1.23E+1
</pre>

See: <a href=dpans3.htm#3.4.1.3>3.4.1.3</a> Text interpreter input number conversion, <a href=dpans12.htm#12.6.1.0558>12.6.1.0558</a> <a href=dpans12.htm#12.6.1.0558>>FLOAT</a>.

<p>
<a href=dpansa12.htm#A.12.3.7>A.12.3.7</a> Text interpreter input number conversion

<p>
The Technical Committee has more than once received the suggestion that the
text interpreter in Standard Forth systems should treat numbers that have an
embedded decimal point, but no exponent, as floating-point numbers rather
than double cell numbers. This suggestion, although it has merit, has always
been voted down because it would break too much existing code; many existing
implementations put the full digit string on the stack as a double number and
use other means to inform the application of the location of the decimal
point.
</blockquote>

<pre>
( ============================================================ )
( Bill Muench \ OntoLogic )
(             \ 3901 Branciforte Drive \ 408 425 8740 )
(             \ Santa Cruz  CA  95065  \ BiMu@aol.com )
</pre>

<h2><a name="reply">TC Reply to Q0004</a></h2>
<pre>
From: Elizabeth D. Rather
Subject: Q0004R, Number Conversion, Official Response
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Wed, 31 May 95 17:04:01 PDT  
Doc#:  X3J14/Q0004R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  May 24, 1995
Title: Response to Request for Interpretation Q0004, Clarification of
Number Conversion
</pre>

<i><blockquote>
<pre>
Subject: ANS Forth Clarification Procedures
To: greg@minerva.com
From: BiMu@aol.com (Identity not yet established)
Date: Mon, 15 May 1995 15:13:21 -0400
Message-Id: <950515151319_119428296@aol.com>
Received: from aol.com by med3.minerva.com ; Mon, 15 May 1995 12:18 PDT
Request for Clairification.
</pre>

I have found the following references to *Text interpreter input number
conversion*.

<p>
The input of Floating-Point numbers is clear, my need for clairification is
with double-cell numbers:

<p>
Will a number with an *embedded* decimal point be converted to a double-cell
number in a Standard Forth system?
</blockquote></i>

Not necessarily.  A Standard System is permitted, but not required, to
convert digit strings with embedded periods as double numbers.
Consequently, a Standard Program cannot rely on any particular
interpretation of such digit strings.

<i><blockquote>
If not, what about <a href=dpansa12.htm#A.12.3.7>A.12.3.7</a> *...should treat numbers that have an embedded
decimal point, but no exponent, as floating-point numbers rather than double
cell numbers. This suggestion, although it has merit, has always been voted
down because it would break too much existing code;* ?
</blockquote></i>

<a href=dpansa12.htm#A.12.3.7>A.12.3.7</a> would be clearer if it read:
The Technical Committee has more than once received the suggestion that
the text interpreter in Standard Forth systems should treat numbers
that have an embedded decimal point, but no exponent, as floating-point
numbers.  This suggestion, although it has merit, has always been voted
down because it would break too much existing code; many existing
implementations put the full digit string on the stack as a double
number and use other means to inform the application of the location of
the decimal point.

Note that the only change I made was to delete the phrase "rather than
double cell numbers" from the first sentence <a href=dpansa12.htm#A.12.3.7>A.12.3.7</a>.  The original
sentence implies that numbers with an embedded decimal point and no
exponent are converted to double numbers in a Standard System.  The
intent of the committee was to allow this behavior in a Standard
System, but not to require it.

<i><blockquote>
Is <a href=dpans8.htm#8.3.2>8.3.2</a> an example or the rule? ( a decimal point at the end)
</blockquote></i>

It is the rule.

<i><blockquote>
<a href=dpans8.htm#8.3.2>8.3.2</a> Text interpreter input number conversion

<p>
When the text interpreter processes a number that is immediately followed by
a decimal point and is not found as a definition name, the text interpreter
shall convert it to a double-cell number.

<p>
For example, entering <a href=dpans6.htm#6.1.1170>DECIMAL</a> 1234 leaves the single-cell number 1234 on the
stack, and entering <a href=dpans6.htm#6.1.1170>DECIMAL</a> 1234. leaves the double-cell number 1234 0 on
the stack.

<p>
See: <a href=dpans3.htm#3.4.1.3>3.4.1.3</a> Text interpreter input number conversion.
</blockquote></i>

Other excerpts deleted.

<pre>
        John R. Hayes
        Applied Physics Laboratory
        Johns Hopkins University
        john.hayes@jhuapl.edu
</pre>

<pre>
Elizabeth D. Rather             "Forth-based products and
FORTH, Inc.                      Services for real-time
111 N. Sepulveda Blvd. #300      applications since 1973"
Manhattan Beach, CA  90266
(800) 55FORTH or (310) 372-8493
FAX (310) 318-7130
</pre>

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
From: Elizabeth D. Rather
Subject: LB015, RE Q0004, Number Conversion
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Wed, 31 May 95 17:04:23 PDT  
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14
Project: X3J14, ANS Forth
Doc#:  X3J14/LB015
Reference Doc#s:  X3J14/Q0004R, X3.215.1994 ANS Forth
Date:  May 31, 1995
Title: Response to Request for Interpretation Q0004, Number Conversion
Ballot Period:  30 Days
Ballot Closes NOON DATE:  June 30, 1995
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130
             erather@forth.com

Statement:
    Document X3J14/Q0004R contains a proposed Response to Request for
    Interpretation Q0004.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?


/------------------------  begin response area----------------------\
|
|  YES____ NO____ ABSTAIN____
|
|  Signature:  [not required for email ballots]
|  Name:
|  Organization:
|
|  Explanation (REQUIRED for NO or ABSTAIN votes):
|    <none>
\------------------------  end response area  ----------------------/

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail or fax or email to me at the above
address, before the closing date & time.

   If replying electronically PLEASE edit only within the response area
   indicated above, inserting any explanatory text in place of <none>.
   Any changes made outside that area will likely be overlooked.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14

Elizabeth D. Rather             "Forth-based products and
FORTH, Inc.                      Services for real-time
111 N. Sepulveda Blvd. #300      applications since 1973"
Manhattan Beach, CA  90266
(800) 55FORTH or (310) 372-8493
FAX (310) 318-7130
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
From: Elizabeth D. Rather
Subject: LBs 14 & 15
To: X3J14 Technical Committee
Cc: l.barra@itic.nw.dc.us
Date: Fri, 07 Jul 95 12:05:04 PDT  
Letter ballots [14 and] 15 closed at noon July 1 with the following results:

        Y  N  A NV
[...]
LB15:  11, 1, 0, 2

Negative vote from Dave Harralson on Letter Ballot 15, with the following
comment:

     I disagree with the response, "not necessarily...."  Section <a href=dpans8.htm#8.3.2>8.3.2</a> clearly
     states that a number with a decimal point that is not in the dictionary
     will be converted to a double-cell number.  If this section is revised,
     I vote yes.

[8.3.2  Text Interpreter Input number conversion
        When the text interpreter process a number that is *immediately
        followed* by a decimal point and is not found as a definition name,
        the text interpreter shall convert it to a double-cell number.]
[Standard quoted by editor; emphasis added where appropriate]

[...]

Thank you for your participation.

Regards,
Elizabeth D. Rather, Chair X3J14

Elizabeth D. Rather             "Forth-based products and
FORTH, Inc.                      Services for real-time
111 N. Sepulveda Blvd. #300      applications since 1973"
Manhattan Beach, CA  90266
(800) 55FORTH or (310) 372-8493
FAX (310) 318-7130
</pre>
a0005.htm/      850787760   500   0     100644  6876      `
<title>ANS Forth RFI 0005: initiation semantics</title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>
The questions covered herein were raised by query

<p>
Q0005, regarding the definition of "initiation semantics".

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0005 as received</a></h2>

<pre>
Subject: Q0005 Request Recognized
To: X3J14@minerva.com
Date: Tue, 12 Sep 95 19:02:13 PDT  
</pre>

The following query has been assigned number Q0005 and has been
tentatively assigned to Jim Rash for drafting a response.
  - Greg Bailey, by direction  950913 0159Z
<hr>

<i><blockquote>
I can not find the definition of " Initiation [semantics]" in the
" <a href=dpans2.htm#2.1>2.1</a> Definitions of terms" but see this term in " <a href=dpans6.htm#6.1.0450>6.1.0450</a> :", p.30.

<p>
Best regards, Michael

<pre>
Michael L. Gassanenko
gml@ag.pu.ru
</pre>
</blockquote></i>

<p>
[Co-author Elizabeth Rather <erather@forth.com> adds:]

<p>
You will see it in <a href=dpans6.htm#6.1.1250>6.1.1250</a> <a href=dpans6.htm#6.1.1250>DOES></a> as well.  This describes the behavior of
a word defined by <a href=dpans6.htm#6.1.0450>:</a> or a <a href=dpans6.htm#6.1.1250>DOES></a> word when it begins to execute.  The
realization that this should be specified separately came rather late in
the process, and I believe you are correct that we have not defined this
term adequately.  I am referring your comment to the TC to see whether they
feel something should be done, such as publishing a clarification.

<p>Thank you for calling it to our attention.


<h2><a name="reply">TC Reply to Q0005</a></h2>

<pre>
From: Elizabeth Rather
Subject: Q0005R, Initiation Semantics, Official Response
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Mon, 19 Feb 96 14:09

Doc#:  X3J14/Q0005R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  February 19, 1996
Title: Response to Request for Interpretation Q0005, Initiation Semantics
</pre>
<hr>

<i><blockquote>
I can not find the definition of "Initiation [semantics]" in the
" <a href=dpans2.htm#2.1>2.1</a> Definitions of terms" but see this term in " <a href=dpans6.htm#6.1.0450>6.1.0450</a> :", p.30.

<p>
Best regards, Michael

<pre>
Michael L. Gassanenko
gml@ag.pu.ru
</pre>
</blockquote></i>

It is noted that the Technical Committee included, in Section <a href=dpans2.htm#2.1>2.1</a> of the
standard, definitions of the terms "compilation semantics" and "execution
semantics".

<p>
For similar reasons, the TC agrees that the standard should also include a
definition of the term "initiation semantics" in Section <a href=dpans2.htm#2.1>2.1</a> Definitions
of Terms:

<dl>
<dt>   initiation semantics:
<dd>      The behavior of a Forth definition, or of the portion of a
      Forth definition following <a href=dpans6.htm#6.1.1250>DOES></a>, when it begins execution.
</dl>

By way of further clarification, when a definition begins execution, the
system may perform implementation-dependent actions such as placing items
on the return stack to allow return to a calling definition.  These actions
are invisible to a standard program except at certain points during the
execution of definitions created with <a href=dpans6.htm#6.1.0450>:</a> (colon) or <a href=dpans6.htm#6.2.0455>:NONAME</a> and during the
execution of the code following <a href=dpans6.htm#6.1.1250>DOES></a>.  At these points, the sole visible
result is the possible presence of the implementation-dependent _nest-sys_
on the return stack.

<p>
Within a given implementation, definitions created with <a href=dpans6.htm#6.1.0450>:</a> (colon) all have
the same initiation semantics.  Similarly for all definitions created with
<a href=dpans6.htm#6.2.0455>:NONAME</a> or <a href=dpans6.htm#6.1.1250>DOES></a>.

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14
Project: X3J14, ANS Forth
Doc#:  X3J14/LB016
Reference Doc#s:  X3J14/Q0005R, X3.215.1994 ANS Forth
Date:  February 19, 1996
Title: Response to Request for Interpretation Q0005, Initiation Semantics
Ballot Period:  30 Days
Ballot Closes NOON DATE:  March 21, 1996
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130
             erather@forth.com

Statement:
    Document X3J14/Q0005R contains a proposed Response to Request for
    Interpretation Q0005.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?


/------------------------  begin response area----------------------\
|
|  YES____ NO____ ABSTAIN____
|
|  Signature:  [not required for email ballots]
|  Name:
|  Organization:
|
|  Explanation (REQUIRED for NO or ABSTAIN votes):
|    <none>
\------------------------  end response area  ----------------------/

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail or fax or email to me at the above
address, before the closing date & time.

   If replying electronically PLEASE edit only within the response area
   indicated above, inserting any explanatory text in place of <none>.
   Any changes made outside that area will likely be overlooked.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
Letter ballot 16 closed at noon March 21 with the following results:

        Y  N  A NV
LB16:  10, 1, 1, 2

"No" vote on LB16 from L. Zettel, with the following comment:

   | I agree with the explanation given for the meaning of "initiation
   | semantics" and with the explanation for the committee's intent in
   | the language of the standard.
   |
   | I do not agree with the declaration of intent to add a formal
   | definition of "initiation semantics" to the Standard.
   |
   |>From: JEThomas@ix.netcom.com (Jonah Thomas)
   |
   |>What the original document said, in <a href=dpans3.htm#3.4.3>3.4.3</a> Semantics, was 'The terms
   |>"initiation semantics" and "run-time semantics" refer to definition
   |>fragments, and have meaning only within the individual glossary
   |>entries where they appear.'


Abstention from John Hayes.
<pre>
a0006.htm/      850791480   500   0     100644  16288     `
<title>ANS Forth RFI 0006: Writing to Input Buffers</title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>
The questions covered herein were raised by query

<p>
Q0006, regarding Writing to Input Buffers.

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0006 as received</a></h2>

<pre>
Subject: Q0006 Request Recognized
To: X3J14@minerva.com
Date: Thu, 05 Oct 95 09:23:38 PDT  
</pre>

The following query has been assigned number Q0005.
   - Greg Bailey, by direction  950913 0159Z
<hr>

Request from TC member Jonah Thomas (Jet.Thomas@minerva.com)

<p>
Here's a question about the Standard:

<p>
When is it allowed to write into input buffers?

<p>
On the surface this is simple:  "A program shall not write into the
input buffer."

<p>
But what about this:

<pre>
{
<a href=dpans6.htm#6.1.0450>:</a> CHANGE-TEXT <a href=dpans6.htm#6.1.2165>S"</a>  <a href=dpans15.htm#15.6.1.2465>WORDS</a> <a href=dpans15.htm#15.6.1.0220>.S</a> " <a href=dpans6.htm#6.1.2165>S"</a> <a href=dpans6.htm#6.1.2160>ROT</a> <a href=dpans6.htm#6.1.2260>SWAP</a> MOVE" <a href=dpans6.htm#6.1.1360>EVALUATE</a> <a href=dpans6.htm#6.1.0460>;</a>

 <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans6.htm#6.1.2216>SOURCE</a> <a href=dpans6.htm#6.1.1260>DROP</a> CHANGE-TEXT <a href=dpans15.htm#15.6.1.0220>.S</a>
}
</pre>

Our input buffer starts out with

<pre>
 <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans6.htm#6.1.2216>SOURCE</a> <a href=dpans6.htm#6.1.1260>DROP</a> CHANGE-TEXT <a href=dpans15.htm#15.6.1.0220>.S</a>
</pre>

When it executes CHANGE-TEXT it has ( ca ) the buffer address on the
stack.  CHANGE-TEXT first provides a string ( ca ca' u ) then another
string ( ca ca' u ca" u") and then evaluates the second string.  The
original buffer is now not the input buffer, now the 2nd string is
the read-only input buffer.  It does <a href=dpans6.htm#6.1.2160>ROT</a> ( ca' u ca ) 
<a href=dpans6.htm#6.1.2260>SWAP</a> ( ca' ca u)
<a href=dpans6.htm#6.1.1900>MOVE</a> and moves the first string into 
the original input buffer, which now
reads

<pre>
 <a href=dpans15.htm#15.6.1.2465>WORDS</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans15.htm#15.6.1.0220>.S</a> <a href=dpans6.htm#6.1.2216>SOURCE</a> <a href=dpans6.htm#6.1.1260>DROP</a> CHANGE-TEXT <a href=dpans15.htm#15.6.1.0220>.S</a>
</pre>

Then it reverts to the changed input buffer and does the final 
<a href=dpans15.htm#15.6.1.0220>.S</a> .

<p>
I say that even if this is legal, it's bad practice.  If you want to 
alter an input buffer, better to copy it into your own private area and
change it however you like and then do <a href=dpans6.htm#6.1.1360>EVALUATE</a> .

<p>
My question is whether this _is_ legal, and why or why not.

<p>
I originally interpreted a previous dpANS document as saying that the
user input buffer, the one pointed to by the obsolescent 
<a href=dpans6.htm#6.2.2290>TIB</a> and <a href=dpans6.htm#6.2.0060>#TIB</a> ,
is read-only.  That makes a different kind of sense to me.  In some
systems it could be a read-only pipe from some other process, or it could
be some special hardware read-only buffer.  It makes sense to me that the
user input buffer should never be modified by a standard program.

<p>
So I can see 4 obvious choices, with perhaps others also available:

<ol>

<li>The current input buffer is read-only; strings which are not the
current input buffer may be written to unless they're read-only for some
other reason.

<li>The current input buffer is read-only as is the user input buffer;
any region of allotted memory is read/write except while it is the input
buffer.

<li>Any region of memory that is EVALUATEd is forever after read-only.

<li>Any region of memory that is EVALUATEd is read-only until the
evaluation is complete -- either by evaluation until the parse area is
empty and return from <a href=dpans6.htm#6.1.1360>EVALUATE</a> or 
<a href=dpans6.htm#6.1.1380>EXIT</a> found in the evaluated string, or
<a href=dpans6.htm#6.1.2050>QUIT</a> or 
<a href=dpans6.htm#6.1.0670>ABORT</a> performed before evaluation is 
finished, or if an ambiguous
condition exists due to the code evaluated.

</ol>

I don't like #3, since I sometimes want to evaluate text that's in block
buffers or file buffers.  #4 could take a lot of figuring to tell whether
it's being violated or not.  I like #1, but it seems to allow some
atrocious practices in standard code.  #2 has the further problem that
there is no way for a program to tell whether an address is in the 
read-only user input buffer, except with 
<a href=dpans6.htm#6.2.2218>SOURCE-ID</a> or 
<a href=dpans6.htm#6.2.2290>TIB</a> , both of which 
are in an optional extension wordset.

<p>
Any ideas?

<h2><a name="reply">TC Reply to Q0006</a></h2>

<pre>
From: Elizabeth Rather
Subject: Q0006R, Writing to Input Buffers, Official Response
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Mon, 19 Feb 96 14:09


Doc#:  X3J14/Q0006R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  February 19, 1996
Title: Response to Request for Interpretation Q0006, Writing to Input Buffers
</pre>

<h3>Q0006:  When is it allowed to write into input buffers?</h3>

Request from TC member Jonah Thomas (Jet.Thomas@minerva.com)

<i><blockquote>
Here's a question about the Standard:

When is it allowed to write into input buffers?
</blockquote></i>

When a standard program receives the address and length of the
'input buffer' from the word  <a href=dpans6.htm#6.1.2216>SOURCE</a>  
it *must* treat this information as though it describes a read-only region of memory.

<p>
This is one of the conditions that must be met in order to compose
code whose processing of 'input buffers' is independent of the
physical and logical characteristics of the diverse 'input sources'
described in the Standard.

<p>
It is logically possible for an application to alter the 'input
buffer' supplied to  <a href=dpans6.htm#6.1.1360>EVALUATE</a>  
while that 'input buffer' is being
processed.  This possibility exists as a special case because the
application actually "owns" and has full control over the buffer
in question.  As owner of the buffer, and both producer and 
consumer of the data it contains, the application can alter this
buffer and manipulate  <a href=dpans6.htm#6.1.0560>>IN</a>  with 
deterministic results, assuming
that it knows the buffer to exist in physically writable memory.

<p>
The Standard does not describe this possibility because the
implied coding methods constitute a special case which is only
usable with  <a href=dpans6.htm#6.1.1360>EVALUATE</a>  and can 
lead to the development of source
language syntax which is not processable from other 'input sources.'

<h3>Relevant text from the Standard:</h3>

<dl>

<dt>
<a href=dpans6.htm#6.1.1360>6.1.1360</a>  <a href=dpans6.htm#6.1.1360>EVALUATE</a>
<dd>
    ... Make the string described ... both the
        'input source' and 'input buffer' ...

<dt>
<a href=dpans6.htm#6.1.2216>6.1.2216</a>  <a href=dpans6.htm#6.1.2216>SOURCE</a>
<dd>
    ... c-addr is the address of, and u is the number of
    characters in, the 'input buffer'.

<dt>
<a href=dpans2.htm#2.1>2.1</a> Definitions of Terms
<dd>
 <dl>
    <dt>input source: <dd> The device, file, block, or other entity
        that supplies characters to refill the 'input buffer'.
    <dt>input buffer: <dd> A region of memory containing the sequence
        of characters from the input source that is currently
        accessible to a program.
 </dl>

<dt>
<a href=dpans3.htm#3.3.3.5>3.3.3.5</a>  Input buffers
<dd>
    The address, length, and content of the 'input buffer' may be
        transient.  A program shall not write into the 'input
        buffer'.  ... the 'input buffer' is either ... or a buffer
        specified by  <a href=dpans6.htm#6.1.1360>EVALUATE</a> .  ...  An ambiguous condition
        exists if a program modifies the contents of the 'input
        buffer'."

</dl>

<h3>Discussion of Technical Committee Intent</h3>

<a href=dpans6.htm#6.2.2040>QUERY</a> and <a href=dpans6.htm#6.2.2290>TIB</a> 
have been deprecated because while some systems have
a discrete *place* called <a href=dpans6.htm#6.2.2290>TIB</a> that is 
exclusively used for storing
the results of <a href=dpans6.htm#6.2.2040>QUERY</a>, other existing systems 
actually use <a href=dpans6.htm#6.2.2290>TIB</a> as a
handle for the current line being interpreted from a file.  While
applications exist making either assumption, these applications can
obviously not work properly on both sorts of systems in general.

<p>Storing into 'input buffers' is disallowed because we permit input
sources to nest indefinitely and it is not practical for systems
that conserve resources to guarantee unique concurrent addressability
of all nested input sources, nor is it practical to create separate
save areas for all current input buffers just in case someone stored
into one of them.  The TC specifically intends that, when input is
coming from refreshable sources, implementations may refresh their
buffers on un-nesting to conserve resources, and that when logically
possible implementations may use transient, shared buffers (as is
common practice with  <a href=dpans7.htm#7.6.1.1790>LOAD</a>  on 
multiprogrammed systems.)  Therefore,
the results of storing into input buffers is stated as ambiguous,
and may even be physically disallowed, as in the case of interpreting
source from read only memory mapped files in some operating systems.

<p>
For similar reasons the address returned by  
<a href=dpans6.htm#6.1.2216>SOURCE</a>  is transient,
and there is specifically no guarantee that any 'input buffer' other
than *the* (current) 'input buffer' is addressable at any time, nor
that this address be valid after nesting or un-nesting.  (Indeed,
in classical multiprogrammed systems the address returned by
<a href=dpans6.htm#6.1.2216>SOURCE</a> is no longer valid after using 
<a href=dpans6.htm#6.1.2450>WORD</a> .)

<p>
The TC expects all Systems to process buffers provided by  
<a href=dpans6.htm#6.1.1360>EVALUATE</a>
in place.  This is logically necessary, in our view, since there are
no upper limits on the lengths of these buffers.  Since it is 
semantically permissible to describe more than half of addressable memory
in an <a href=dpans6.htm#6.1.1360>EVALUATE</a>  string it is not in 
general *possible* to copy such a
string elsewhere and address it consistently with the definition
of  <a href=dpans6.htm#6.1.2216>SOURCE</a> .

<p>
Systems are not allowed to alter the contents of 'input buffers' 
provided through  <a href=dpans6.htm#6.1.1360>EVALUATE</a> .  At the 
same time, applications are responsible for guaranteeing that the 
buffers they provide to  <a href=dpans6.htm#6.1.1360>EVALUATE</a>  are
static in both address and content until the  
<a href=dpans6.htm#6.1.1360>EVALUATE</a>  has completed.

<p>
<a href=dpans6.htm#6.1.1360>EVALUATE</a> is a special case since the 
input buffer is literally
the area of memory provided to <a href=dpans6.htm#6.1.1360>EVALUATE</a> and 
is as such static.
The application "owns" the memory it occupies, and the mechanism
for messaging the interpreter via <a href=dpans6.htm#6.1.0560>>IN</a> 
(as well as the syntax of
Forth) implies no prefetching or preprocessing of input buffers
is necessary or appropriate.

<p>
Given these conditions, it *is* deterministic for an application to
store (with great care) into <a href=dpans6.htm#6.1.1360>EVALUATE</a> buffers 
that it knows to be
active, although such methods pertain exclusively to 
<a href=dpans6.htm#6.1.1360>EVALUATE</a> and
certainly not to any other input stream source.

<p>
However, as the Standard is written, any program that does this is
not a standard program.

<hr>

It has been brought to the TC's attention that there exists at least
one implementation which moves an <a href=dpans6.htm#6.1.1360>EVALUATE</a> 
string to a separate work
area for processing.  As a separate but related question we have
been asked whether a system which does this, and which therefore
fails John Hayes' test suite, is compliant.  (The test in question
fails if the buffer address and length returned by 
<a href=dpans6.htm#6.1.2216>SOURCE</a> occurring
in an <a href=dpans6.htm#6.1.1360>EVALUATE</a> string differ from the 
address and length of the
argument provided to EVALUATE.)

<p>
The system in question is definitely not compliant since both the
letter of the standard and the intent of the TC are that 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>
strings be processed in place.  The fact that John's test suite is
able to detect the deviation confirms its visibility to application
code, assuming that any such code ever makes such a comparison.

<p>
The ambiguity documented for storing into 'input buffers' serves to
mitigate the seriousness of this noncompliance since any program
which stores into an active <a href=dpans6.htm#6.1.1360>EVALUATE</a> 
string is environmentally dependent on the system's resolution of 
the ambiguity.  Nevertheless, the
Standard clearly states that the <a href=dpans6.htm#6.1.1360>EVALUATE</a> 
string *is* the 'input
buffer' (by definition a region of memory), and that 
<a href=dpans6.htm#6.1.2216>SOURCE</a> returns
the address and length of this region of memory.  This is an unqualified 
promise to people writing standard programs, and any system
which breaks that promise must document its nonstandard implementations 
of <a href=dpans6.htm#6.1.1360>EVALUATE</a> and <a href=dpans6.htm#6.1.2216>SOURCE</a>.

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14
Project: X3J14, ANS Forth
Doc#:  X3J14/LB017
Reference Doc#s:  X3J14/Q0006R, X3.215.1994 ANS Forth
Date:  February 19, 1996
Title:  Response to Request for Interpretation Q0006, Writing to Input Buffers
Ballot Period:  30 Days
Ballot Closes NOON DATE:  March 21, 1996
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130
             erather@forth.com

Statement:
    Document X3J14/Q0006R contains a proposed Response to Request for
    Interpretation Q0006.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?


/------------------------  begin response area----------------------\
|
|  YES____ NO____ ABSTAIN____
|
|  Signature:  [not required for email ballots]
|  Name:
|  Organization:
|
|  Explanation (REQUIRED for NO or ABSTAIN votes):
|    <none>
\------------------------  end response area  ----------------------/

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail or fax or email to me at the above
address, before the closing date & time.

   If replying electronically PLEASE edit only within the response area
   indicated above, inserting any explanatory text in place of <none>.
   Any changes made outside that area will likely be overlooked.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
Letter ballot 17 closed at noon March 21 with the following results:

        Y  N  A NV
LB17:  12, 0, 1, 1

Abstention from John Hayes.
</pre>
a0007.htm/      850788960   500   0     100644  16914     `
<title>ANS Forth RFI 0007: distinction between "immediacy" and
"special compilation semantics"</title>

This document is produced by TC X3J14 as its clarification of questions
raised about ANSI X3.215-1994, American National Standard for Information
Systems - Programming Languages - Forth.

<p>
The questions covered herein were raised by query

<p>
Q0007, regarding the distinction between "immediacy" and "special
        compilation semantics".

<p>There are four parts in this document:

<ol>
<li><a href="#query">The original question as received.</a>
<li><a href="#reply">The TC's reply.</a>
<li><a href="#ballot">The Letter Ballot issued by TC Chair.</a>
<li><a href="#results">TC Chair's statement of ballot results.</a>
</ol>

<h2><a name="query">Q0007 as received</a></h2>

<pre>
Subject: Q0007 Request Recognized & Draft 0
To: X3J14@minerva.com
Cc: wykoh@pado.krict.re.kr
Date: Sat, 23 Dec 95 02:11:38 PST  
</pre>

The following query has been assigned number Q0007.
   - Greg Bailey, by direction  951223 0700Z
<hr>
Wonyong Koh wrote on Fri, 22 Dec 95 16:27:03 PST  <a href=dpans6.htm#6.1.0450>:</a>

<i><blockquote>
Dear Mr. Bailey,

<p>
   I would like you to ask to interpret the ANS Forth Stanard.
You might already know about it. In recent discussion in comp.
lang.forth I and Mr. Jonah Thamas have different opinion on
<a href=dpans6.htm#6.1.0950>CONSTANT</a>. I interpret that making <a href=dpans6.htm#6.1.0950>CONSTANT</a> create <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>
words does not violate ANS Standard while Mr. Thomas thinks
it does. 

<p>
   I think that it is a obvious choice to make <a href=dpans6.htm#6.1.0950>CONSTANT</a> words
STATE-smart in subroutine-threaded Forth (i.e. native Forth
compiler). <a href=dpans6.htm#6.1.1710>IMMEDIATE</a> <a href=dpans6.htm#6.1.0950>CONSTANT</a> words pushes a number on top of
the stack in interpretation state while compiles in-line
machine code in compilation state. I beleive that it is not
TC's intention to leave significant number of native-code
Forth compilers out of ANS Standard System. Please clarify this.

<pre>
Wonyong Koh
wykoh@pado.krict.re.kr
</pre>
</blockquote></i>

<h2><a name="reply">TC Reply to Q0007</a></h2>

<pre>
From: Elizabeth Rather
Subject: Q0007R, "immediacy" and "special compilation semantics", Official Response
To: X3J14 Technical Committee
Cc: lbarra@itic.nw.dc.us
Date: Mon, 19 Feb 96 14:10


Doc#:  X3J14/Q0007R
Reference Doc#:  X3.215.1994 ANS Forth
Date:  February 19, 1996
Title: Response to Request for Interpretation Q0007, Clarifying the
distinction between "immediacy" and "special compilation semantics"
</pre>

<h3>Q0007:  Clarifying the distinction between "immediacy" and
        "special compilation semantics".</h3>

Wonyong Koh wrote on Fri, 22 Dec 95 16:27:03 PST:

<i><blockquote>
Dear Mr. Bailey,

<p>
   I would like you to ask to interpret the ANS Forth Stanard.
You might already know about it. In recent discussion in comp.
lang.forth I and Mr. Jonah Thamas have different opinion on
<a href=dpans6.htm#6.1.0950>CONSTANT</a>. I interpret that making <a href=dpans6.htm#6.1.0950>CONSTANT</a> create <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>
words does not violate ANS Standard while Mr. Thomas thinks
it does.

<p>
   I think that it is a obvious choice to make <a href=dpans6.htm#6.1.0950>CONSTANT</a> words
STATE-smart in subroutine-threaded Forth (i.e. native Forth
compiler). <a href=dpans6.htm#6.1.1710>IMMEDIATE</a> <a href=dpans6.htm#6.1.0950>CONSTANT</a> words pushes a number on top of
the stack in interpretation state while compiles in-line
machine code in compilation state. I beleive that it is not
TC's intention to leave significant number of native-code
Forth compilers out of ANS Standard System. Please clarify this.

<pre>
Wonyong Koh
wykoh@pado.krict.re.kr
</pre>
</blockquote></i>

Wonyong Koh is literally correct, in the sense that optimizing
compilers which add special compilation semantics to classes of
definitions such as  CONSTANTs  are specifically supported by
ANS Forth.  Applying the concept, in these terms, to ANS Forth
has very clear meaning and leads to no inconsistencies.

<p> However, using the term "immediate" to speak of such compilation
semantics is not recommended since this term carries with it all of
the implications of the implementation model prescribed by earlier
standards such as FORTH-83.  Attempting to discuss the advanced
capabilities available to ANS Forth compilers in terms of "immediacy"
ineviteably leads to confusion, misunderstanding, and the eventual
"discovery" of apparent inconsistencies that do not, in fact, exist in
the Standard (although they may indeed exist in a particular
implementation.)  This in turn can lead to arguments over moot points.

<p>
In particular, a  <a href=dpans6.htm#6.1.0950>CONSTANT</a>  with special compilation semantics
is *not* the same thing as is a  <a href=dpans6.htm#6.1.0950>CONSTANT</a>  declared as follows:

<pre>
     123 <a href=dpans6.htm#6.1.0950>CONSTANT</a> JOE  <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>
</pre>

... but in ANS Forth terms, this usage is the *only* sense in
which the word "immediate" or the concept of "immediacy" is
defined or meaningful.  Always discuss ANS Forth compilation
semantics as such, not as "immediacy", for clarity and to avoid
pitfalls, even when discussing an implementation that uses
classical immediacy as its way for expressing compilation
semantics.

<h3>Analysis of Specific Case</h3>

However, upon review of the usenet discussion you reference, it would
appear that you may have added special compilation semantics to
CONSTANTs without adding all of the communication with the compiler
that is necessary to deliver the proper semantics in all cases when
such CONSTANTs are used.  The test case that failed seems likely to
have encountered one of these probable inconsistencies, as opposed to
"caring" whether the <a href=dpans6.htm#6.1.0950>CONSTANT</a> definition in question was "immediate"
in your implementation as such.

<p>
At the same time, the ability to declare an <a href=dpans6.htm#6.1.1710>IMMEDIATE</a> constant,
as in   123 <a href=dpans6.htm#6.1.0950>CONSTANT</a> JOE  <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>   had been precluded.

<p>
Careful review of the semantic requirements for definitions
when used in compilation, interpretation, and execution, as
well as the results of obtaining execution tokens and using
them with  <a href=dpans6.htm#6.1.1370>EXECUTE</a>  or  <a href=dpans6.htm#6.2.0945>COMPILE,</a> , and when referenced
following  <a href=dpans6.htm#6.2.2530>[COMPILE]</a>  (if  <a href=dpans6.htm#6.2.0945>COMPILE,</a>  or  <a href=dpans6.htm#6.2.2530>[COMPILE]</a> are to
be supported) should make it clear that significant flow of
information is required between the compiler and the definition
when extending normally "default" compilation and/or
interpretation semantics of compliant definitions.

<p>
*The standard does not define the way in which this information
flow takes place.*  While a standard program may extend "macros"
such as control flow words as illustrated in the examples,
it is not possible to define words of the sort that normally
have "default" compilation and interpretation semantics such
that they have special compilation or interpretation semantics
without depending on implementation specific knowledge.  If
this is done without knowing how to communicate with the
compiler, the resulting definitions may deliver the correct
semantics in *some*, but cannot in *all*, cases.

<p>
For example, consider a Standard Program that adds special
compilation semantics to  <a href=dpans6.htm#6.1.1290>DUP</a>  as in the following example:

<pre>
    <a href=dpans6.htm#6.1.2410>VARIABLE</a> #DUPS
    <a href=dpans6.htm#6.1.0450>:</a> <a href=dpans6.htm#6.1.1290>DUP</a>   1 #DUPS <a href=dpans6.htm#6.1.0130>+!</a>  <a href=dpans6.htm#6.1.2033>POSTPONE</a> <a href=dpans6.htm#6.1.1290>DUP</a> <a href=dpans6.htm#6.1.0460>;</a>  <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>
</pre>

If all this did was to count compilations of <a href=dpans6.htm#6.1.1290>DUP</a>, it would
be compliant since the additional work done affects nothing
else and is therefore OK (See section 3.)

<p>
However, this definition does not comply because it does not
yield the correct semantics in all cases.

<ul>
 <li> It compiles correctly
 <li> It interprets incorrectly
 <li> (what it compiles) executes correctly
 <li> Its tick, when EXECUTEd or COMPILE,'d executes incorrectly
 <li> <a href=dpans6.htm#6.2.2530>[COMPILE]</a> does not work correctly with it.
</ul>


And, coincidentally, execution of its tick is abysmally slow
(which would take more information flow to resolve, but which
is not required since it only affects performance as opposed
to correct execution.)

<p> If the word was made state smart to distinguish between interpret
and compile states, so that it counted #DUPS and did the <a href=dpans6.htm#6.1.2033>POSTPONE</a> when
in compilation state and simply executed <a href=dpans6.htm#6.1.1290>DUP</a> when interpreting, then
the situation changes but is still not correct:

<ul>
 <li> It compiles correctly
 <li> It interprets correctly
 <li> (what it compiles) executes correctly
 <li> Its tick, when EXECUTEd is correct if in interpret state
     at the time <a href=dpans6.htm#6.1.1370>EXECUTE</a> is invoked, but is incorrect if in compile
     state at the time
 <li> A definition into which its tick is  COMPILE,'d  runs
     correctly if the definition runs in interpret state but fails
     if it is run in compile state
 <li> <a href=dpans6.htm#6.2.2530>[COMPILE]</a> does not work correctly with it.
</ul>

And execution of the tick, even when correct, is still slow.

<p>
There is, at minimum, a bidirectional flow of information between
the compiler / interpreter and the definition of  <a href=dpans6.htm#6.1.1290>DUP</a>  that must
occur around ticking and <a href=dpans6.htm#6.2.2530>[COMPILE]</a> ; in its absence, the compiler
does not have any way of asking the definition for an *execution*
token, and the definition does not have any way to provide one;
and, in the case of <a href=dpans6.htm#6.2.2530>[COMPILE]</a>, the compiler has no way of knowing
that this definition is supposed to be treated as though it had
default compilation semantics.

<p>
The TC did not attempt specifying this compiler interface because
it affects only new capabilities which were almost universally
impossible in earlier standards, and active experimentation is
still underway with these new capabilities, including as it
appears your own.  At some time in the future after more has
been learned it may be appropriate to standardize such a message
passing mechanism, however at present any *application* which
adds compilation semantics like this will need to incorporate
implementation dependent code... or it will yield noncompliant
definitions, as illustrated above.

<p> In the problem you have been discussing, you are the implementor
so you certainly have the power to create and then employ the
necessary interface.  However, it appears that you have overlooked
this necessity, and that is probably why you have been having
difficulty.

<h3>Discussion of Immediacy, Transparency, and Compliance</h3>

In FORTH-83 it was necessary to document the "I" (Immediate) attribute
of every standard word (and for that matter every word in each
application) because the application needed to be aware of this
attribute in order to make correct selections between use of COMPILE
and <a href=dpans6.htm#6.2.2530>[COMPILE]</a> , and in order to predict the consequences of using what
are now called "execution tokens".  Since knowledge of immediate
versus nonimmediate attribute for each existing word appeared in
application programs in both explicit and implicit ways, it was not
practical to change the "immediacy" of any word in the system, nor
indeed in most applications.  The attribute of immediacy was the only
tool for making or discussing the distinc- tion between compilation
and execution behavior, and the need for program awareness of this
attribute as well as its inelastic nature led to a number of well
known inconsistencies.  In addition, it made compliance with FORTH-83
impractically cumbersome for many advanced compilers, including the
incremental optimizing sort.

<p>
ANS Forth addresses these problems by defining all words in terms
of explicit compilation, interpretation, and execution semantics;
by defining such words as  <a href=dpans6.htm#6.1.1710>IMMEDIATE</a>  and  <a href=dpans6.htm#6.2.2530>[COMPILE]</a> and the effects
of <a href=dpans6.htm#6.1.1370>EXECUTE</a> with execution tokens as specific transformations and
selections on these semantics; by introducing  <a href=dpans6.htm#6.1.2033>POSTPONE</a>  to solve
a well known dilemma in selection of the appropriate semantics;
and finally by deleting the "I" designations since it is no longer
necessary for the application programmer to be aware of them as
such.  Finally, having done these things, it is possible for a
compiler to add any desired compilation semantics, including those
useful for optimization purposes, to definitions without affecting
the use of those definitions by applications.  <a href=dpans6.htm#6.1.1710>IMMEDIATE</a> remains
available for application use, but its effects are specified in
semantic terms that can coexist with arbitrary default compilation
semantics.

<p>
In ANS Forth, the existence and nature of compilation semantics
that are in effect messages to the compiler is concealed well
from the programmer, and the application code is the same whether
or not, for example,  <a href=dpans6.htm#6.1.1290>DUP</a>  is "immediate" (in the old terms) or
"has special compilation semantics" (in ANS Forth terms).  The
only significant caveat is that when a system supports  <a href=dpans6.htm#6.2.2530>[COMPILE]</a>
it must be very careful to treat all definitions that the
Standard says have "default" compilation semantics, but to
which the system has given "special" compilation semantics
for its own purposes, as though they had "default" compilation
semantics when referenced by  <a href=dpans6.htm#6.2.2530>[COMPILE]</a>.

<p>
An implementation complies with the standard if all Forth words
and classes of words defined by the Standard behave, in all cases,
consistently with the semantics prescribed in the Standard.  The
test for correctness is specifically limited to semantics, as
opposed to nonsemantic considerations such as, for example,
the size, speed, or binary representation of compiled programs.

<p>
Please refer to <a href=dpansd.htm#D.4>D.4</a>, <a href=dpansd.htm#D.5>D.5</a>, <a href=dpansd.htm#D.6.7>D.6.7</a>, and <a href=dpanse.htm#E.4.1>E.4.1</a> for further discussion
of optimizing compilers and ANS Forth handling of "immediacy".

<h2><a name="ballot">Letter Ballot</a></h2>

<pre>
X3 Subgroup Letter Ballot
Authorized by X3 Procedures - Distributed by X3 Subgroup X3J14
Project: X3J14, ANS Forth
Doc#:  X3J14/LB018
Reference Doc#s:  X3J14/Q0007R, X3.215.1994 ANS Forth
Date:  February 19, 1996
Title:  Response to Request for Interpretation Q0007, Clarifying the
distinction between "immediacy" and "special compilation semantics"
Ballot Period:  30 Days
Ballot Closes NOON DATE:  March 21, 1996
Respond to:  greg@minerva.com
        or:  Elizabeth D. Rather, Chair
             FORTH, Inc.
             111 N. Sepulveda Blvd.  Suite 300
             Manhattan Beach, CA  90266
             (310) 372-8493    FAX (310) 318-7130
             erather@forth.com

Statement:
    Document X3J14/Q0007R contains a proposed Response to Request for
    Interpretation Q0007.

Question:
    Do you agree that this response represents the intended interpretation of
    X3.215.1994 ANS Forth?


/------------------------  begin response area----------------------\
|
|  YES____ NO____ ABSTAIN____
|
|  Signature:  [not required for email ballots]
|  Name:
|  Organization:
|
|  Explanation (REQUIRED for NO or ABSTAIN votes):
|    <none>
\------------------------  end response area  ----------------------/

INSTRUCTIONS:
Please return the entire letter ballot with your response _either_ by email
to greg@minerva.com _or_ by regular mail or fax or email to me at the above
address, before the closing date & time.

   If replying electronically PLEASE edit only within the response area
   indicated above, inserting any explanatory text in place of <none>.
   Any changes made outside that area will likely be overlooked.

All TC members must vote.  Failure to vote in two consecutive ballots may
cause you to lose your voting rights in X3J14.

Thank you for your participation.

Elizabeth D. Rather, Chair, X3J14
</pre>

<h2><a name="results">Results of Letter Ballot</a></h2>

<pre>
Letter ballot 18 closed at noon March 21 with the following results:

        Y  N  A NV
LB18:  12, 0, 1, 1

Abstention from John Hayes.
</pre>
dpans.htm/      850760640   500   0     100644  13692     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<HR>
<H2>American National Standard
for Information Systems </H2>

<H1>Programming Languages </H1>

<H1>Forth</H1>

<P>

Secretariat
<BR>
<B>Computer and Business Equipment Manufacturers Association</B>
<BR>
Approved:  March 24, 1994
<BR>
<B>American National Standards Institute, Inc.</B>
<P>


<HR>
<P>

Copyright (c) 1994 by Technical Committee X3J14. All rights reserved.
<P>

This is a working document of Technical Committee X3J14 which
represents the last draft of ANS Forth submitted to ANSI for publication. 
Permission is hereby granted to copy this document provided that it is
copied in its entirety without alteration or as altered by (1) adding text
that is clearly marked as an insertion; (2) shading or highlighting
existing text; and/or (3) deleting examples. 
<P>

Specifically, permission is granted to use this working document as the
foundation for textbooks, system manuals, and online documentation so
long as the requirements in the preceding paragraph are met and the
resulting product addresses a technical need that is not practically met by
the official ANS. 
<P>

<DL><DT><B>NOTE:</B> 
<DD>This file is provided as a working document of the TC for
public review and comment as well as documentation uses described above. 
<I>It is not intended as a substitute for the official ANS Forth document
published by ANSI.</I> In the event of conflict, only the printed document
X3.215-1994 represents the official ANS Forth. </DL>

<P>

To obtain the official standard, please contact the American
National Standards Institute Sales Department, at (212) 642-4900 or FAX
(212) 302-1286, or Global Engineering Documents, at (800) 854-7179 or
FAX (303) 843-9880, and request Document X3.215-1994. Thank you very
much for your interest. 

<P>


<HR>

<h3>HTML version 3.2</h3>

<a href=notes.htm>Editorial Notes</a>
<br>
<a href=rfilist.htm>Requests for Interpretations</a>
<p>
<hr>
<a name=toc>
<H3>Table of Contents</H3>
</a>

 
<P>


<hr>
<A href=dpans1.htm#foreword>Foreword</A>
<BR>
<A href=dpans1.htm#x3.membership>X3 Membership</A>
<BR>
<A href=dpans1.htm#x3j14.membership>X3J14 Membership</A>
<BR>
<P>


<hr>
<A href=dpans1.htm#1.>1.</a> Introduction
<BR>
<DL>
<A href=dpans1.htm#1.1>1.1</a> Purpose
<BR>
<A href=dpans1.htm#1.2>1.2</a> Scope
<BR>
<A href=dpans1.htm#1.3>1.3</a> Document organization
<BR>
<A href=dpans1.htm#1.4>1.4</a> Future directions
<BR></DL>

<P>


<hr>
<A href=dpans2.htm>2.</a> Terms, notation, and references
<BR>
<DL>
<A href=dpans2.htm#2.1>2.1</a> Definitions of terms
<BR>
<A href=dpans2.htm#2.2>2.2</a> Notation
<BR>
<dl>
<A href=dpans2.htm#2.2.1>2.2.1</a> Numeric notation
<BR>
<A href=dpans2.htm#2.2.2>2.2.2</a> Stack notation
<BR>
<A href=dpans2.htm#2.2.3>2.2.3</a> Parsed-text notation
<BR>
<A href=dpans2.htm#2.2.4>2.2.4</a> Glossary notation
<BR></dl>
<A href=dpans2.htm#2.3>2.3</a> References
<BR></DL>

<P>

<hr>
<A href=dpans3.htm>3.</a> Usage requirements
<BR>
<DL>
<A href=dpans3.htm#3.1>3.1</a> Data types
<BR>
<dl>
<a href=dpans3.htm#3.1.1>3.1.1</a> Data-type relationships
<BR>
<a href=dpans3.htm#3.1.2>3.1.2</a> Character types
<BR>
<a href=dpans3.htm#3.1.3>3.1.3</a> Single-cell types
<BR>
<a href=dpans3.htm#3.1.4>3.1.4</a> Cell-pair types
<BR>
<a href=dpans3.htm#3.1.5>3.1.5</a> System types
<BR></dl>
<A href=dpans3.htm#3.2>3.2</a> The implementation environment
<BR>
<dl>
<A href=dpans3.htm#3.2.1>3.2.1</a> Numbers
<BR>
<A href=dpans3.htm#3.2.2>3.2.2</a> Arithmetic
<BR>
<A href=dpans3.htm#3.2.3>3.2.3</a> Stacks
<BR>
<A href=dpans3.htm#3.2.4>3.2.4</a> Operator terminal
<BR>
<A href=dpans3.htm#3.2.5>3.2.5</a> Mass storage
<BR>
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
<BR></dl>
<A href=dpans3.htm#3.3>3.3</a> The Forth dictionary
<BR>
<dl>
<A href=dpans3.htm#3.3.1>3.3.1</a> Name space
<BR>
<A href=dpans3.htm#3.3.2>3.3.2</a> Code space
<BR>
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space
<BR></dl>
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter
<BR>
<dl>
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing
<BR>
<A href=dpans3.htm#3.4.2>3.4.2</a> Finding definition names
<BR>
<A href=dpans3.htm#3.4.3>3.4.3</a> Semantics
<BR>
<A href=dpans3.htm#3.4.4>3.4.4</a> Possible actions on an ambiguous condition
<BR>
<A href=dpans3.htm#3.4.5>3.4.5</a> Compilation
</dl>
<BR></DL>

<P>

<hr>
<A href=dpans4.htm>4.</a> Documentation requirements
<BR>
<DL>
<A href=dpans4.htm#4.1>4.1</a> System documentation
<BR>
<A href=dpans4.htm#4.2>4.2</a> Program documentation
<BR></DL>

<P>

<hr>
<A href=dpans5.htm>5.</a> Compliance and labeling
<BR>
<DL>
<A href=dpans5.htm#5.1>5.1</a> ANS Forth systems
<BR>
<A href=dpans5.htm#5.2>5.2</a> ANS Forth programs
<BR></DL>

<P>

<hr>
<A href=dpans6.htm>6.</a> Glossary
<BR>
<DL>
<A href=dpans6.htm#6.1>6.1</a> Core words
<BR>
<A href=dpans6.htm#6.2>6.2</a> Core extension words
<BR></DL>

<P>

<hr>
<A href=dpans7.htm>7.</a> The optional Block word set
<BR>
<DL>
<A href=dpans7.htm#7.1>7.1</a> Introduction
<BR>
<A href=dpans7.htm#7.2>7.2</a> Additional terms
<BR>
<A href=dpans7.htm#7.3>7.3</a> Additional usage requirements
<BR>
<A href=dpans7.htm#7.4>7.4</a> Additional documentation requirements
<BR>
<A href=dpans7.htm#7.5>7.5</a> Compliance and labeling
<BR>
<A href=dpans7.htm#7.6.1>7.6.1</a> Block words
<BR>
<A href=dpans7.htm#7.6.2>7.6.2</a> Block extension words
<BR></DL>

<P>

<hr>
<A href=dpans8.htm>8.</a> The optional Double-Number word set
<BR>
<DL>
<A href=dpans8.htm#8.1>8.1</a> Introduction
<BR>
<A href=dpans8.htm#8.2>8.2</a> Additional terms and notation
<BR>
<A href=dpans8.htm#8.3>8.3</a> Additional usage requirements
<BR>
<A href=dpans8.htm#8.4>8.4</a> Additional documentation requirements
<BR>
<A href=dpans8.htm#8.5>8.5</a> Compliance and labeling
<BR>
<A href=dpans8.htm#8.6.1>8.6.1</a> Double-Number words
<BR>
<A href=dpans8.htm#8.6.2>8.6.2</a> Double-Number extension words
<BR></DL>

<P>

<hr>
<A href=dpans9.htm>9.</a> The optional Exception word set
<BR>
<DL>
<A href=dpans9.htm#9.1>9.1</a> Introduction
<BR>
<A href=dpans9.htm#9.2>9.2</a> Additional terms and notation
<BR>
<A href=dpans9.htm#9.3>9.3</a> Additional usage requirements
<BR>
<A href=dpans9.htm#9.4>9.4</a> Additional documentation requirements
<BR>
<A href=dpans9.htm#9.5>9.5</a> Compliance and labeling
<BR>
<A href=dpans9.htm#9.6.1>9.6.1</a> Exception words
<BR>
<A href=dpans9.htm#9.6.2>9.6.2</a> Exception extension words
<BR></DL>

<P>

<hr>
<A href=dpans10.htm>10.</a> The optional Facility word set
<BR>
<DL>
<A href=dpans10.htm#10.1>10.1</a> Introduction
<BR>
<A href=dpans10.htm#10.2>10.2</a> Additional terms and notation
<BR>
<A href=dpans10.htm#10.3>10.3</a> Additional usage requirements
<BR>
<A href=dpans10.htm#10.4>10.4</a> Additional documentation requirements
<BR>
<A href=dpans10.htm#10.5>10.5</a> Compliance and labeling
<BR>
<A href=dpans10.htm#10.6.1>10.6.1</a> Facility words
<BR>
<A href=dpans10.htm#10.6.2>10.6.2</a> Facility extension words
<BR></DL>

<P>

<hr>
<A href=dpans11.htm>11.</a> The optional File-Access word set
<BR>
<DL>
<A href=dpans11.htm#11.1>11.1</a> Introduction
<BR>
<A href=dpans11.htm#11.2>11.2</a> Additional terms
<BR>
<A href=dpans11.htm#11.3>11.3</a> Additional usage requirements
<BR>
<A href=dpans11.htm#11.4>11.4</a> Additional documentation requirements
<BR>
<A href=dpans11.htm#11.5>11.5</a> Compliance and labeling
<BR>
<A href=dpans11.htm#11.6.1>11.6.1</a> File-Access words
<BR>
<A href=dpans11.htm#11.6.2>11.6.2</a> File-Access extension words
<BR></DL>

<P>

<hr>
<A href=dpans12.htm>12.</a> The optional Floating-Point word set
<BR>
<DL>
<A href=dpans12.htm#12.1>12.1</a> Introduction
<BR>
<A href=dpans12.htm#12.2>12.2</a> Additional terms and notation
<BR>
<A href=dpans12.htm#12.3>12.3</a> Additional usage requirements
<BR>
<A href=dpans12.htm#12.4>12.4</a> Additional documentation requirements
<BR>
<A href=dpans12.htm#12.5>12.5</a> Compliance and labeling
<BR>
<A href=dpans12.htm#12.6.1>12.6.1</a> Floating-Point words
<BR>
<A href=dpans12.htm#12.6.2>12.6.2</a> Floating-Point extension words
<BR></DL>

<P>

<hr>
<A href=dpans13.htm>13.</a> The optional Locals word set
<BR>
<DL>
<A href=dpans13.htm#13.1>13.1</a> Introduction
<BR>
<A href=dpans13.htm#13.2>13.2</a> Additional terms and notation
<BR>
<A href=dpans13.htm#13.3>13.3</a> Additional usage requirements
<BR>
<A href=dpans13.htm#13.4>13.4</a> Additional documentation requirements
<BR>
<A href=dpans13.htm#13.5>13.5</a> Compliance and labeling
<BR>
<A href=dpans13.htm#13.6.1>13.6.1</a> Locals words
<BR>
<A href=dpans13.htm#13.6.2>13.6.2</a> Locals extension words
<BR></DL>

<P>

<hr>
<A href=dpans14.htm>14.</a> The optional Memory-Allocation word set
<BR>
<DL>
<A href=dpans14.htm#14.1>14.1</a> Introduction
<BR>
<A href=dpans14.htm#14.2>14.2</a> Additional terms and notation
<BR>
<A href=dpans14.htm#14.3>14.3</a> Additional usage requirements
<BR>
<A href=dpans14.htm#14.4>14.4</a> Additional documentation requirements
<BR>
<A href=dpans14.htm#14.5>14.5</a> Compliance and labeling
<BR>
<A href=dpans14.htm#14.6.1>14.6.1</a> Memory-Allocation words
<BR></DL>

<P>

<hr>
<A href=dpans15.htm>15.</a> The optional Programming-Tools word set
<BR>
<DL>
<A href=dpans15.htm#15.1>15.1</a> Introduction
<BR>
<A href=dpans15.htm#15.2>15.2</a> Additional terms and notation
<BR>
<A href=dpans15.htm#15.3>15.3</a> Additional usage requirements
<BR>
<A href=dpans15.htm#15.4>15.4</a> Additional documentation requirements
<BR>
<A href=dpans15.htm#15.5>15.5</a> Compliance and labeling
<BR>
<A href=dpans15.htm#15.6.1>15.6.1</a> Programming-Tools words
<BR>
<A href=dpans15.htm#15.6.2>15.6.2</a> Programming-Tools extension words
<BR></DL>

<P>

<hr>
<A href=dpans16.htm>16.</a> The optional Search-Order word set
<BR>
<DL>
<A href=dpans16.htm#16.1>16.1</a> Introduction
<BR>
<A href=dpans16.htm#16.2>16.2</a> Additional terms and notation
<BR>
<A href=dpans16.htm#16.3>16.3</a> Additional usage requirements
<BR>
<A href=dpans16.htm#16.4>16.4</a> Additional documentation requirements
<BR>
<A href=dpans16.htm#16.5>16.5</a> Compliance and labeling
<BR>
<A href=dpans16.htm#16.6.1>16.6.1</a> Search-Order words
<BR>
<A href=dpans16.htm#16.6.2>16.6.2</a> Search-Order extension words
<BR></DL>

<P>

<hr>
<A href=dpans17.htm>17.</a> The optional String word set
<BR>
<DL>
<A href=dpans17.htm#17.1>17.1</a> Introduction
<BR>
<A href=dpans17.htm#17.2>17.2</a> Additional terms and notation
<BR>
<A href=dpans17.htm#17.3>17.3</a> Additional usage requirements
<BR>
<A href=dpans17.htm#17.4>17.4</a> Additional documentation requirements
<BR>
<A href=dpans17.htm#17.5>17.5</a> Compliance and labeling
<BR>
<A href=dpans17.htm#17.6.1>17.6.1</a> String words
<BR></DL>
<P>

<hr>
<A href=dpansa1.htm>A.</a> Rationale (informative annex)
<BR>
<DL>
<A href=dpansa1.htm>A.1</a> Introduction
<BR>
<A href=dpansa2.htm>A.2</a> Terms and notation
<BR>
<A href=dpansa3.htm>A.3</a> Usage requirements
<BR>
<A href=dpansa4.htm>A.4</a> Documentation requirements
<BR>
<A href=dpansa5.htm>A.5</a> Compliance and labeling
<BR>
<A href=dpansa6.htm>A.6</a> Glossary
<BR>
<A href=dpansa7.htm>A.7</a> The optional Block word set
<BR>
<A href=dpansa8.htm>A.8</a> The optional Double-Number word set
<BR>
<A href=dpansa9.htm>A.9</a> The optional Exception word set
<BR>
<A href=dpansa10.htm>A.10</a> The optional Facility word set
<BR>
<A href=dpansa11.htm>A.11</a> The optional File-Access word set
<BR>
<A href=dpansa12.htm>A.12</a> The optional Floating-Point word set
<BR>
<A href=dpansa13.htm>A.13</a> The optional Locals word set
<BR>
<A href=dpansa14.htm>A.14</a> The optional Memory-Allocation word set
<BR>
<A href=dpansa15.htm>A.15</a> The optional Programming-Tools word set
<BR>
<A href=dpansa16.htm>A.16</a> The optional Search-Order word set
<BR>
<A href=dpansa17.htm>A.17</a> The optional String word set
<BR></DL>

<P>

<hr>
<A href=dpansb.htm>B.</a> Bibliography (informative annex)
<BR>
<DL>
<A href=dpansb.htm#Industry.standards>Industry standards</A>
<BR>
<A href=dpansb.htm#Books>Books</A>
<BR>
<A href=dpansb.htm#Journals>Journals, magazines and newsletters</A>
<BR>
<A href=dpansb.htm#Selected.articles>Selected articles</A>
<BR></DL>

<P>

<hr>
<A href=dpansc.htm>C.</a> Perspective (informative annex)
<BR>
<DL>
<A href=dpansc.htm#C.1>C.1</a> Features of Forth
<BR>
<A href=dpansc.htm#C.2>C.2</a> History of Forth
<BR>
<A href=dpansc.htm#C.3>C.3</a> Hardware implementations of Forth
<BR>
<A href=dpansc.htm#C.4>C.4</a> Standardization efforts
<BR>
<A href=dpansc.htm#C.5>C.5</a> Programming in Forth
<BR>
<A href=dpansc.htm#C.6>C.6</a> Multiprogrammed systems
<BR>
<A href=dpansc.htm#C.7>C.7</a> Design and management considerations
<BR>
<A href=dpansc.htm#C.8>C.8</a> Conclusion
<BR></DL>

<P>

<hr>
<A href=dpansd.htm>D.</a> Compatibility analysis of ANS Forth
(informative annex)
<BR>
<DL>
<A href=dpansd.htm#D.1>D.1</a> FIG Forth (circa 1978)
<BR>
<A href=dpansd.htm#D.2>D.2</a> Forth-79
<BR>
<A href=dpansd.htm#D.3>D.3</a> Forth-83
<BR>
<A href=dpansd.htm#D.4>D.4</a> Recent developments
<BR>
<A href=dpansd.htm#D.5>D.5</a> ANS Forth approach
<BR>
<A href=dpansd.htm#D.6>D.6</a> Differences from Forth-83
<BR></DL>

<P>

<hr>
<A href=dpanse.htm>E.</a> ANS Forth portability guide (informative
annex)
<BR>
<DL>
<A href=dpanse.htm#E.1>E.1</a> Introduction
<BR>
<A href=dpanse.htm#E.2>E.2</a> Hardware peculiarities
<BR>
<A href=dpanse.htm#E.3>E.3</a> Number representation
<BR>
<A href=dpanse.htm#E.4>E.4</a> Forth system implementation
<BR>
<A href=dpanse.htm#E.5>E.5</a> ROMed application disciplines and
conventions
<BR>
<A href=dpanse.htm#E.6>E.6</a> Summary
<BR></DL>

<P>

<hr>
<A href=dpansf.htm>F.</a> Alphabetic list of words (informative
annex)
<BR>
<hr>
<P>
</BODY>
</HTML>
dpans1.htm/     845513040   500   0     100644  17467     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>


<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans2.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
Table of Contents
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>American National Standard for Information Systems</H1>

<H1>Programming Languages</H1>

<H1>Forth</H1>


Secretariat

<BR>
Computer and Business Equipment Manufacturers Association

<BR>
Approved:  March 24, 1994

<BR>
American National Standards Institute, Inc.

<P>


Copyright (c) 1994 by Technical Committee X3J14.  
All rights reserved.

<P>


This is a working document of Technical Committee X3J14 which represents
the last draft of ANS Forth submitted to ANSI for publication. 
Permission is hereby granted to copy this document provided that it is
copied in its entirety without alteration or as altered by (1) adding
text that is clearly marked as an insertion; (2) shading or highlighting
existing text; and/or (3) deleting examples. 

<P>


Specifically, permission is granted to use this working document as the
foundation for textbooks, system manuals, and online documentation so
long as the requirements in the preceding paragraph are met and the
resulting product addresses a technical need that is not practically met
by the official ANS. 

<P>


<b>NOTE:</b> This file is provided as a working document of the TC for public
review and comment as well as documentation uses described above.  It is
not intended as a substitute for the official ANS Forth document
published by ANSI.  In the event of conflict, only the printed document
X3.215-1994 represents the official ANS Forth. 

<P>


To obtain the official standard, please contact the American National
Standards Institute Sales Department, at (212) 642-4900 or FAX (212)
302-1286, or Global Engineering Documents, at (800) 854-7179 or FAX
(303) 843-9880, and request Document X3.215-1994.  Thank you very much
for your interest. 



<HR>
<a name=foreword>
<H1>Foreword</H1>
</a>


(This foreword is not a part of
American National Standard X3.215-1994)

<P>


Forth is a language for direct communication between human beings and
machines.  Using natural-language diction and machine-oriented syntax,
Forth provides an economical, productive environment for interactive
compilation and execution of programs.  Forth also provides low-level
access to computer-controlled hardware, and the ability to extend the
language itself.  This extensibility allows the language to be quickly
expanded and adapted to special needs and different hardware systems. 

<P>


Forth was invented by Mr.  Charles Moore to increase programmer
productivity without sacrificing machine efficiency.  Forth is a layered
environment containing the elements of a computer language as well as
those of an operating system and a machine monitor.  This extensible,
layered environment provides for highly interactive program development
and testing. 

<P>


In the interests of transportability of application software written in
Forth, standardization efforts began in the mid-1970s by an
international group of users and implementors who adopted the name
<B>Forth Standards Team</B>.  This effort resulted in the Forth-77
Standard.  As the language continued to evolve, an interim Forth-78
Standard was published by the Forth Standards Team.  Following Forth
Standards Team meetings in 1979, the Forth-79 Standard was published in
1980.  Major changes were made by the Forth Standards Team in the
Forth-83 Standard, which was published in 1983. 

<P>


The first meeting of the Technical Committee on Forth Programming
Systems was convened by the Organizing Committee of the X3J14 Forth
Technical Committee on August 3, 1987, and has met subsequently on
November 11-12, 1987, February 10-12, 1988, May 25-28, 1988, August
10-13, 1988, October 26-29, 1988, January 25-28, 1989, May 3-6, 1989,
July 26-29, 1989, October 25-28, 1989, January 24-27, 1990, May 22-26,
1990, August 21-25, 1990, November 6-10,1990, January 29-February 2,
1991, May 3-4, 1991, June 16-19, 1991, July 30-August 3, 1991, March
17-21, 1992, October 13-17, 1992, January 26-30, 1993, June 28-30, 1993,
and June 21, 1994. 

<P>

Requests for interpretation, suggestions for improvement or addenda, or
defect reports are welcome.  They should be sent to the X3 Secretariat,
Computer and Business Equipment Manufacturers Association, 1250 Eye
Street, NW, Suite 200, Washington, DC 20005. 



<HR>
<a name=x3.membership>
<H1>X3 Membership</H1>
</a>

This standard was processed and approved for submittal to ANSI by the
Accredited Standards Committee on Information Processing Systems, X3.
Committee approval of this standard does not necessarily imply that all
committee members voted for its approval.  At the time it approved this
standard, the X3 Committee had the following members:

<P>


James D. Converse, Chair
Donald C. Loughry, Vice-Chair
Joanne Flanagan, Secretary

<P>




<PRE>
Producer Group                          Name of Representative
--------------                          ----------------------
AMP Incorporated                        Edward Kelly
                                        Charles Brill (Alt.)

AT&T/NCR Corporation                    Thomas W. Kern
                                        Thomas F. Frost (Alt.)

Apple Computer, Inc.                    Karen Higginbottom

Compaq Computers                        James Barnes

Digital Equipment Corporation           Delbert Shoemaker
                                        Kevin Lewis

Hitachi America Ltd.                    John Neumann
                                        Kei Yamashita (Alt.)

Hewlett Packard                         Donald C. Loughry

Bull HN Information Systems Inc.        William George

IBM Corporation                         Joel Urman
                                        Mary Anne Lawler (Alt.)

Unisys Corporation                      John Hill
                                        Stephen P. Oksala (Alt.)

Sony Corporation of America             Michael Deese

Storage Technology Corporation          Joseph S. Zajaczkowski
                                        Samuel D. Cheatham (Alt.)

Sun Microsystems, Inc.                  Scott Jameson
                                        Gary S. Robinson (Alt.)

* Xerox Corporation                     Dwight McBain
                                        Roy Pierce (Alt.)

3M Company                              Edie T. Morioka
                                        Paul D. Jahnke (Alt.

</PRE>
<P>


Consumers Group

<BR>
---------------


<PRE>
Boeing Company                          Catherine Howells
                                        Andrea Vanosdoll (Alt.)

Eastman Kodak Company                   James Converse
                                        Michael Nier (Alt.)

General Services Administration         Douglas Arai
                                        Larry L. Jackson (Alt.)

Guide International Inc.                Frank Kirshenbaum
                                        Harold Kuneke (Alt.)

** Hughes Aircraft Company              Harold Zebrack

National Communications Systems         Dennis Bodson

Northern Telecom Inc.                   Mel Woinsky
                                        Subhash Patel (Alt.)

** Recognition Tech Users Association   Herbert P. Schantz
                                        Edwin Hale (Alt.)

Share Inc.                              Gary AinsworthDavid Thewis (Alt.)

U. S. Department of Defense             William Rinehuls
                                        J. Pasquariello (Alt.)

U. S. Department of Energy              Alton Cox
                                        Lawrence A. Wasson (Alt.)

Wintergreen Information Services        John Wheeler
</PRE>
<P>



General Interest Group

<BR>
----------------------


<PRE>
American Nuclear Society                Geraldine C. Main
                                        Sally Hartzell (Alt.)

Assn. of the Institute for Certification of Computer Professionals
                                        Kenneth Zemrowski

Nat'l Institute of Standards and Technology     
                                        Robert E. Rountree
                                        Micharl Hogan (Alt.)

Neville & Associates                    Carlton Neville
________________________

* Abstain      ** Non-Response
</PRE>

<P>




<HR>
<a name=x3j14.membership>
<H3>X3J14 Membership</H3>
</a>

At the time it approved this draft of the proposed American National
Standard, the Technical Committee X3J14 on the Forth Programming
Language had the following members:

<P>


Elizabeth Rather, Chair

<BR>
Mitch Bradley, acting Vice-Chair

<BR>
Don Colburn, Secretary

<BR>
John Rible, Technical Editor

<BR>
Len Zettel, Vocabulary Representative

<BR>
Greg Bailey, Technical Subcommittee Chair

<BR>

<P>




<PRE>
Organization Represented                Name of Representative
------------------------                ----------------------
ATHENA Programming, Inc.                Greg Bailey
                                        Howe Fong (Alt.)

Bradley Forthware                       Mitch Bradley

Creative Solutions, Inc.                Don Colburn

Ford Motor Company                      Leonard F. Zettel, Jr.

FORTH, Inc.                             Elizabeth Rather
                                        Dennis Ruffer (Alt.)

Institute for Applied Forth Research    Lawrence Forsley
                                        Horace Simmons (Alt.)

Johns Hopkins University, Applied Physics Lab.  
                                        John Hayes

Mephistopheles Systems                  Dave Harralson

NASA/Goddard Space Flight Center        James Rash

Nomadic Software                        John K. Stevenson

Unisyn, Inc.                            Gary Betts
                                        Stephen Egbert (Alt.)

Up and Running                          Martin Tracy

Vesta Technology                        Jack Woehr

Individual Members                      Loring Craymer
                                        John Rible
                                        E. (Jet) Thomas

X3 Liasons                              Clyde R. Camp
                                        Kathleen McMillan
</PRE>

<P>


The following organizations and individuals have also participated in this
project as Technical Committee members, alternates, or observers.  The
Technical Committee recognizes and respects their contributions:

<P>


Organizations

<BR>
-------------


<PRE>
British Columbia Inst. of Tech.  MCI Telecommunications Corp.
Computer Cowboys                 Micromotion
Computer Sciences Corp.          MicroProcessor Engineering Ltd.
Computer Strategies, Inc.        National Institute of Standards & Technology
Digalog Corp.                    NCR Medical Systems Group
Embedded Sys. Programming Mag.   Performance Packages, Inc.
Forth Interest Group (FIG)       Purdue University
H.B. Pascal & Co., Inc.          Robert Berkey Services
Harris Semiconductor             Shaw Laboratories
IBM Corporation                  Social Security Administration
IEEE                             Software Engineering
Kelly Enterprises                Texas Instruments
Laboratory Microsystems, Inc.    The Dickens Company
Maxtor Corp.
</PRE>

<P>


Individuals

<BR>
-----------


<PRE>
David J. Angel  Ray Duncan      Charles Moore   Dean Sanderson
Wil Baden       Douglas Fishman Mike Nemeth     George Shaw
Robert Berkey   Tom Hand        Harry Pascal    Gerald Shifrin
Ron Braithwaite Gregory Ilg     Stephen Pelc    Robert Smith
Jack Brown      Charles Keane   Dean Perrine    Tyler Sperry
Chris Colburn   Guy M. Kelly    David C. Petty  Tom Zimmer
Ted Dickens     Andrew Kobziar  Bill Ragsdale   James Ryland
John Dorband    Martin Lascelles

</PRE>
<P>

<hr>
<H1>AMERICAN NATIONAL STANDARD ANSI X3.215-1994 American National
Standard for Information Systems</A></H1>



<H3>Programming Language</A></H3>


<H3>Forth</A></H3>



<HR>
<a name=1.>
<H1>1. Introduction</H1>
</a>


<hr>
<a name=1.1>
<H2>1.1 Purpose</H2>
</a>

The purpose of this Standard is to promote the portability of Forth programs
for use on a wide variety of computing systems, to facilitate the
communication of programs, programming techniques, and ideas among Forth
programmers, and to serve as a basis for the future evolution of the Forth
language.

<P>


<hr>
<a name=1.2>
<H2>1.2 Scope</H2>
</a>

This Standard specifies an interface between a Forth System and a Forth
Program by defining the words provided by a Standard System.

<p>
<code>
See:
<a href=dpansa1.htm#A.1.2>A.1.2</a> Scope
</code>
<p>

<hr>
<a name=1.2.1>
<H3>1.2.1 Inclusions</H3>
</a>

This Standard specifies:
<P>


<UL>
<LI>the forms
that a program written in the Forth language may take;
<LI>the rules for interpreting the meaning of a program and its data.
</UL>

<P>


<hr>
<a name=1.2.2>
<H3>1.2.2 Exclusions</H3>
</a>

This Standard does not specify:
<P>


<UL>
<LI>the mechanism
by which programs are transformed for use on computing
systems;
<LI>the operations
required for setup and control of the use of programs
on computing systems;
<LI>the method
of transcription of programs or their input or output data
to or from a storage medium;
<LI>the program
and Forth system behavior when the rules of this Standard
fail to establish an interpretation;
<LI>the size
or complexity of a program and its data that will exceed the
capacity of any specific computing system or the capability of a particular
Forth system;
<LI>the physical
properties of input/output records, files, and units;
<LI>the physical
properties and implementation of storage.
</UL>

<P>


<hr>
<a name=1.3>
<H2>1.3 Document organization</H2>
</a>

<P>


<hr>
<a name=1.3.1>
<H3>1.3.1 Word sets</H3>
</a>

This Standard groups Forth words and capabilities into word sets under a name
indicating some shared aspect, typically their common functional area. Each
word set may have an extension, containing words that offer additional
functionality.  These words are not required in an implementation of the word
set.

<P>


The <B>Core</B> word set, defined in sections 1 through 6, contains the
required
words and capabilities of a Standard System.  The other word sets, defined in
sections 7 through 17, are optional, making it possible to provide Standard
Systems with tailored levels of functionality.

<p>
<code>
See:
<a href=dpansa1.htm#A.1.3.1>A.1.3.1</a> Word sets
</code>
<p>



<hr>
<a name=1.3.1.1>
<H4>1.3.1.1 Text sections</H4>
</a>

Within each word set, section 1 contains introductory and explanatory material
and section 2 introduces terms and notation used throughout the Standard.
There are no requirements in these sections.

<P>


Sections 3 and 4 contain the usage and documentation requirements,
respectively, for Standard Systems and Programs, while section 5 specifies
their labeling.

<P>


<hr>
<a name=1.3.1.2>
<H4>1.3.1.2 Glossary sections</H4>
</a>

Section 6 of each word set specifies the required behavior of the definitions
in the word set and the extensions word set.

<P>


<hr>
<a name=1.3.2>
<H3>1.3.2 Annexes</H3>
</a>

The annexes do not 
contain any required material.
<P>


<a href=dpansa1.htm>Annex A</a> 
provides some of the rationale behind the committee's decisions in
creating this Standard, as well as implementation examples.  It has the same
section numbering as the body of the Standard to make it easy to relate each
requirements section to its rationale section.

<P>


<a href=dpansb.htm>Annex B</a> 
is a short bibliography on Forth.

<P>


<a href=dpansc.htm>Annex C</a> 
provides an introduction to Forth.

<P>


<a href=dpansd.htm>Annex D</a> 
discusses the compatibility of ANS Forth with earlier Forths,
emphasizing the differences from Forth-83.

<P>


<a href=dpanse.htm>Annex E</a> 
presents some techniques for writing portable programs in ANS Forth.

<P>


<a href=dpansf.htm>Annex F</a> 
includes the words from all word sets in a single list, and serves as
an index of ANS Forth words.

<P>


<hr>
<a name=1.4>
<H2>1.4 Future directions</H2>
</a>



<hr>
<A name=1.4.1>
<H3>1.4.1 New technology</H3>
</a>

This Standard adopts certain words and practices that are increasingly found
in common practice.  New words have also been adopted to ease creation of
portable programs.

<P>

<hr>
<A name=1.4.2>
<H3>1.4.2 Obsolescent features</H3>
</a>

This Standard adopts certain words and practices that cause some previously
used words to become obsolescent.  Although retained here because of their
widespread use, their use in new implementations or new programs is
discouraged, because they may be withdrawn from future revisions of the
Standard.

<P>

This Standard designates the following words as obsolescent:
<P>



<PRE>
<a href=dpans6.htm#6.2.0060>6.2.0060</a>        #TIB
<a href=dpans15.htm#15.6.2.1580>15.6.2.1580</a>     FORGET
<a href=dpans6.htm#6.2.2240>6.2.2240</a>        SPAN
<a href=dpans6.htm#6.2.0970>6.2.0970</a>        CONVERT
<a href=dpans6.htm#6.2.2040>6.2.2040</a>        QUERY
<a href=dpans6.htm#6.2.2290>6.2.2290</a>        TIB
<a href=dpans6.htm#6.2.1390>6.2.1390</a>        EXPECT
</PRE>

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans2.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpans10.htm/    851247240   500   0     100644  8758      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans9.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans13.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=10.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>10. The optional Facility word set</H1>


<hr>
<A name=10.1>
<H2>10.1 Introduction</H2>
</a>


<hr>
<A name=10.2>
<H2>10.2 Additional terms and notation</H2>
</a>

None.
<P>


<hr>
<A name=10.3>
<H2>10.3 Additional usage requirements</H2>
</a>


<hr>
<A name=10.3.1>
<H3>10.3.1 Character types</H3>
</a>

Programs that use more than seven bits of a character by 
<a href=dpans10.htm#10.6.2.1305>10.6.2.1305</a>
EKEY have an environmental dependency.
<P>

<code>
See:
<A href=dpans3.htm#3.1.2>3.1.2</a> Character types
</code>
<P>


<hr>
<A name=10.3.2>
<H3>10.3.2 Environmental queries</H3>
</a>

Append table 10.1 to table 3.5.
<P>

<code>
See:
<a href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 10.1 - Environmental query strings


<PRE>
String          Value data type   Constant?   Meaning
------          ---------------   ---------   -------
FACILITY        flag              no          facility word set present
FACILITY-EXT    flag              no          facility extensions word set present

</PRE>

<P>

<hr>
<A name=10.4>
<H2>10.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=10.4.1>
<H3>10.4.1 System documentation</H3>
</a>


<hr>
<A name=10.4.1.1>
<H4>10.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>encoding of keyboard events 
(<a href=dpans10.htm#10.6.2.1305>10.6.2.1305</a> EKEY);
<LI>duration of a system clock tick;
<LI>repeatability to be expected from execution of 
<a href=dpans10.htm#10.6.2.1905>10.6.2.1905</a> MS.
</UL>
<P>


<hr>
<A name=10.4.1.2>
<H4>10.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI><a href=dpans10.htm#10.6.1.0742>10.6.1.0742</a> AT-XY 
operation can't be performed on user output device.
</UL>
<P>


<hr>
<A name=10.4.1.3>
<H4>10.4.1.3 Other system documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>

<hr>
<A name=10.4.2>
<H3>10.4.2 Program documentation</H3>
</a>


<hr>
<A name=10.4.2.1>
<H4>10.4.2.1 Environmental dependencies</H4>
</a>

<UL>
<LI>using more than seven bits of a character in 
<a href=dpans10.htm#10.6.2.1305>10.6.2.1305</a> EKEY.
</UL>
<P>


<hr>
<A name=10.4.2.2>
<H4>10.4.2.2 Other program documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>

<hr>
<A name=10.5>
<H2>10.5 Compliance and labeling</H2>
</a>


<hr>
<A name=10.5.1>
<H3>10.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Facility word set</B> shall be appended to
the label of any Standard System that provides all of the Facility word
set.
<P>

The phrase <B>Providing name(s) from the Facility Extensions word
set</B> shall be appended to the label of any Standard System that
provides portions of the Facility Extensions word set.
<P>

The phrase <B>Providing the Facility Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
Facility and Facility Extensions word sets.
<P>


<hr>
<A name=10.5.2>
<H3>10.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Facility word set</B> shall be appended to
the label of Standard Programs that require the system to provide the
Facility word set.
<P>

The phrase <B>Requiring name(s) from the Facility Extensions word
set</B> shall be appended to the label of Standard Programs that require
the system to provide portions of the Facility Extensions word set.
<P>

The phrase <B>Requiring the Facility Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the Facility and Facility Extensions word sets.
<P>


<hr>
<A name=10.6>
<H2>10.6 Glossary</H2>
</a>


<hr>
<A name=10.6.1>
<H3>10.6.1 Facility words</H3>
</a>


<hr>
<A name=10.6.1.0742>
<code>
10.6.1.0742 <b>AT-XY</b>
</code>
</a>
<BR>
<B>at-x-y</B>        FACILITY
<BR>
<pre>
	( u1 u2 -- )
</pre>
<P>

Perform implementation-dependent steps so that the next character
displayed will appear in column u1, row u2 of the user output device,
the upper left corner of which is column zero, row zero.  An ambiguous
condition exists if the operation cannot be performed on the user output
device with the specified parameters.

<p>
<code>
See:
<a href=dpansa10.htm#A.10.6.1.0742>A.10.6.1.0742 AT-XY</a>
</code>
<P>

<hr>
<A name=10.6.1.1755>
<code>
10.6.1.1755 <b>KEY?</b>
</code>
</a>
<BR>
<B>key-question</B>  FACILITY
<BR>
<pre>
	( -- flag )
</pre>
<P>

If a character is available, return true.  Otherwise, return false.  If
non-character keyboard events are available before the first valid
character, they are discarded and are subsequently unavailable.  The
character shall be returned by the next execution of 
<a href=dpans6.htm#6.1.1750>KEY</a>.
<P>

After KEY? returns with a value of true, subsequent executions of KEY?
prior to the execution of KEY or 
<a href=dpans10.htm#10.6.2.1305>EKEY</a> also return true, without
discarding keyboard events.

<p>
<code>
See:
<a href=dpansa10.htm#A.10.6.1.1755>A.10.6.1.1755 KEY?</a>
</code>
<P>


<hr>
<A name=10.6.1.2005>
<code>
10.6.1.2005 <b>PAGE</b>
</code>
</a>
<BR>
FACILITY
<BR>
<pre>
	( -- )
</pre>
<P>

Move to another page for output.  Actual function depends on the output
device.  On a terminal, PAGE clears the screen and resets the cursor
position to the upper left corner.  On a printer, PAGE performs a form
feed.
<P>



<hr>
<A name=10.6.2>
<H3>10.6.2 Facility extension words</H3>
</a>


<hr>
<A name=10.6.2.1305>
<code>
10.6.2.1305 <b>EKEY</b>
</code>
</a>
<BR>
      <B>e-key</B> FACILITY EXT
<BR>
<pre>
	( -- u )
</pre>
<P>

Receive one keyboard event u.  The encoding of keyboard events is
implementation defined.
<P>

<code>
See:    
<A href=dpans10.htm#10.6.1.1755>10.6.1.1755 KEY?</a> ,
<A href=dpans6.htm#6.1.1750>6.1.1750 KEY</a> ,
<a href=dpansa10.htm#A.10.6.2.1305>A.10.6.2.1305 EKEY</a>
</code>
<P>



<hr>
<A name=10.6.2.1306>
<code>
10.6.2.1306 <b>EKEY&gt;CHAR</b>
</code>
</a>
<BR>
<B>e-key-to-char</B> FACILITY EXT
<BR>
<pre>
	( u -- u false | char true )
</pre>
<P>

If the keyboard event u corresponds to a character in the
implementation-defined character set, return that character and true.
Otherwise return u and false.


<p>
<code>
See:
<a href=dpansa10.htm#A.10.6.2.1306>A.10.6.2.1306 EKEY&gt;CHAR</a>
</code>
<P>


<hr>
<A name=10.6.2.1307>
<code>
10.6.2.1307 <b>EKEY?</b>
</code>
</a>
<BR>
<B>e-key-question</B>        FACILITY EXT
<BR>
<pre>
	( -- flag )
</pre>
<P>

If a keyboard event is available, return true.  Otherwise return false.
The event shall be returned by the next execution of 
<a href=dpans10.htm#10.6.2.1305>EKEY</a>.
<P>

After EKEY? returns with a value of true, subsequent executions of EKEY?
prior to the execution of 
<a href=dpans6.htm#6.1.1750>KEY</a>, 
<a href=dpans10.htm#10.6.1.1755>KEY?</a> 
or EKEY also return true, referring
to the same event.

<P>


<hr>
<A name=10.6.2.1325>
<code>
10.6.2.1325 <b>EMIT?</b>
</code>
</a>
<BR>
<B>emit-question</B> FACILITY EXT
<BR>
<pre>
	( -- flag )
</pre>
<P>

flag is true if the user output device is ready to accept data and the
execution of 
<a href=dpans6.htm#6.1.1320>EMIT</a> 
in place of EMIT? would not have suffered an
indefinite delay.  If the device status is indeterminate, flag is true.

<p>
<code>
See:
<a href=dpansa10.htm#A.10.6.2.1325>A.10.6.2.1325 EMIT?</a>
</code>
<P>


<hr>
<A name=10.6.2.1905>
<code>
10.6.2.1905 <b>MS</b>
</code>
</a>
<BR>
FACILITY EXT
<BR>
<pre>
	( u -- )
</pre>
<P>

Wait at least u milliseconds.

<p>
<b>Note:</b>   The actual length and variability of the time period depends
upon the implementation-defined resolution of the system clock and
upon other system and computer characteristics beyond the scope of
this Standard.


<p>
<code>
See:
<a href=dpansa10.htm#A.10.6.2.1905>A.10.6.2.1905 MS</a>
</code>
<P>


<hr>
<A name=10.6.2.2292>
<code>
10.6.2.2292 <b>TIME&DATE</b>
</code>
</a>
<BR>
<B>time-and-date</B> FACILITY EXT
<BR>
<pre>
	( -- +n1 +n2 +n3 +n4 +n5 +n6 )
</pre>
<P>

Return the current time and date.  +n1 is the second {0...59}, +n2 is
the minute {0...59}, +n3 is the hour {0...23}, +n4 is the day {1...31}
+n5 is the month {1...12}, and +n6 is the year (e.g., 1991).

<p>
<code>
See:
<a href=dpansa10.htm#A.10.6.2.2292>A.10.6.2.2292 TIME&DATE</a>
</code>
<P>



<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans11.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans11.htm/    851247240   500   0     100644  27837     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans10.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans12.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=11.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>11. The optional File-Access word set</H1>

<p>
<code>
See:
<a href=dpansa11.htm#A.11>A.11</a> The optional File-Access word set
</code>
<p>

<hr>
<A name=11.1>
<H2>11.1 Introduction</H2>
</a>

These words provide access to mass storage in the form of <B>files</B>
under the following assumptions:

<UL>
<LI>files are provided by a host operating system;
<LI>file names are represented as character strings;
<LI>the format of file names is determined by the host operating system;
<LI>an open file is identified by a single-cell file identifier (fileid);
<LI>file-state information (e.g., position, size) is managed by the
host operating system;
<LI>file contents are accessed as a sequence of characters;
<LI>file read operations return an actual transfer count, which can
differ from the requested transfer count.
</UL>

<P>

<hr>
<A name=11.2>
<H2>11.2 Additional terms</H2>
</a>

<dl>
<dt><b>file-access method:</b>
<dd>A permissible means of accessing a file, such as <B>read/write</B> or <B>read only</B>.

<dt><b>file position:</b>
<dd>The character offset from the start of the file.

<dt><b>input file:</b>
<dd>The file, containing a sequence of lines, that is the input source.
</dl>


<hr>
<A name=11.3>
<H2>11.3 Additional usage requirements</H2>
</a>



<hr>
<A name=11.3.1>
<H3>11.3.1 Data types</H3>
</a>

Append table 11.1 to 
<a href=dpans3.htm#table.3.1>table 3.1</a>.
<P>

Table 11.1 - Data types
<P>



<PRE>
Symbol  Data type               Size on stack
------  ---------               -------------
ior     I/O results             1 cell
fam     file access method      1 cell
fileid  file identifiers        1 cell
</PRE>

<P>

<hr>
<A name=11.3.1.1>
<H4>11.3.1.1 File identifiers</H4>
</a>

File identifiers are implementation-dependent single-cell values that
are passed to file operators to designate specific files.  Opening a
file assigns a file identifier, which remains valid until closed.


<P>

<hr>
<A name=11.3.1.2>
<H4>11.3.1.2 I/O results</H4>
</a>

I/O results are single-cell numbers indicating the result of I/O
operations.  A value of zero indicates that the I/O operation completed
successfully; other values and their meanings are
implementation-defined.  Reaching the end of a file shall be reported as
zero.

<P>

An I/O exception in the execution of a File-Access word that can return
an I/O result shall not cause a 
<a href=dpans9.htm#9.6.1.2275>THROW</a>; exception indications are
returned in the ior.

<P>

<hr>
<A name=11.3.1.3>
<H4>11.3.1.3 File access methods</H4>
</a>

File access methods are implementation-defined single-cell
values.

<P>

<hr>
<A name=11.3.1.4>
<H4>11.3.1.4 File names</H4>
</a>

A character string containing the name of the file.  The file name may
include an implementation-dependent path name.  The format of file names
is implementation defined.

<P>

<hr>
<A name=11.3.2>
<H3>11.3.2 Blocks in files</H3>
</a>

If the File-Access word set is implemented, the 
<a href=dpans7.htm>Block word set</a> shall be
implemented.

<P>

Blocks may, but need not, reside in files.  When they do:
<P>

<UL>
<LI>Block numbers may be mapped to one or more files by
implementation-defined means. An ambiguous condition exists if a
requested block number is not currently mapped;
<LI>An 
<a href=dpans7.htm#7.6.1.2400>UPDATE</a>d 
block that came from a file shall be transferred back
to the same file.
</UL>

<p>
<code>
See:
<a href=dpansa11.htm#A.11.3.2>A.11.3.2</a> Blocks in files
</code>
<p>


<hr>
<A name=11.3.3>
<H3>11.3.3 Environmental queries</H3>
</a>

Append table 11.2 to
table 3.5.

<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 11.2 - Environmental query strings
<P>



<PRE>
String         Value data type   Constant?  Meaning
------         ---------------   ---------  -------
FILE            flag             no         file word set present
FILE-EXT        flag             no         file extensions word set present
</PRE>

<P>

<hr>
<A name=11.3.4>
<H3>11.3.4 Input source</H3>
</a>

The File-Access word set creates another input source for the text
interpreter.  When the input source is a text file, 
<a href=dpans7.htm#7.6.1.0790>BLK</a> shall contain
zero, 
<a href=dpans6.htm#6.2.2218>SOURCE-ID</a> 
shall contain the fileid of that text file, and the
input buffer shall contain one line of the text file.

<P>

Input with 
<a href=dpans11.htm#11.6.1.1718>INCLUDED</a>, 
<a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a>, 
<a href=dpans7.htm#7.6.1.1790>LOAD</a> and 
<a href=dpans6.htm#6.1.1360>EVALUATE</a> shall be nestable
in any order to at least eight levels.

<P>

A program that uses more than eight levels of input-file nesting has an
environmental dependency.

<P>

<code>
See: 
<A href=dpans3.htm#3.3.3.5>3.3.3.5</a> Input buffers,
<A href=dpans9.htm#9.>9.</a> Optional Exception word set.
</code>
<P>


<hr>
<A name=11.3.5>
<H3>11.3.5 Other transient regions</H3>
</a>

The list of words using memory in transient regions is extended to
include <A href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S".

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions
</code>
<P>


<P>

<hr>
<A name=11.3.6>
<H3>11.3.6 Parsing</H3>
</a>

When parsing from a text file using a space delimiter, control
characters shall be treated the same as the space character.

<P>

Lines of at least 128 characters shall be supported.  A program that
requires lines of more than 128 characters has an environmental
dependency.

<P>

A program may reposition the parse area within the input buffer by
manipulating the contents of 
<a href=dpans6.htm#6.1.0560>&gt;IN</a>.  
More extensive repositioning can be
accomplished using 
<a href=dpans6.htm#6.2.2182>SAVE-INPUT</a> and 
<a href=dpans6.htm#6.2.2148>RESTORE-INPUT</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing
</code>
<P>

<hr>
<A name=11.4>
<H2>11.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=11.4.1>
<H3>11.4.1 System documentation</H3>
</a>


<hr>
<A name=11.4.1.1>
<H4>11.4.1.1 Implementation-defined options</H4>
</a>


<UL>
<LI>file access methods used by 
<a href=dpans11.htm#11.6.1.0765>11.6.1.0765</a> BIN, 
<a href=dpans11.htm#11.6.1.1010>11.6.1.1010</a> CREATE-FILE, 
<a href=dpans11.htm#11.6.1.1970>11.6.1.1970</a> OPEN-FILE, 
<a href=dpans11.htm#11.6.1.2054>11.6.1.2054</a> R/O, 
<a href=dpans11.htm#11.6.1.2056>11.6.1.2056</a> R/W,
and 
<a href=dpans11.htm#11.6.1.2425>11.6.1.2425</a> W/O;
<LI>file exceptions;
<LI>file line terminator 
(<a href=dpans11.htm#11.6.1.2090>11.6.1.2090</a> READ-LINE);
<LI>file name format 
(<a href=dpans11.htm#11.3.1.4>11.3.1.4</a> File names);
<LI>Information returned by 
<a href=dpans11.htm#11.6.2.1524>11.6.2.1524</a> FILE-STATUS;
<LI>Input file state after an exception 
(<a href=dpans11.htm#11.6.1.1717>11.6.1.1717</a> INCLUDE-FILE,
<a href=dpans11.htm#11.6.1.1718>11.6.1.1718</a> INCLUDED);
<LI>ior values and meaning 
(<a href=dpans11.htm#11.3.1.2>11.3.1.2</a> I/O results);
<LI>maximum depth of file input nesting 
(<a href=dpans11.htm#11.3.4>11.3.4</a> Input source);
<LI>maximum size of input line 
(<a href=dpans11.htm#11.3.6>11.3.6</a> Parsing);
<LI>methods for mapping block ranges to files 
(<a href=dpans11.htm#11.3.2>11.3.2</a> Blocks in files);
<LI>number of string buffers provided 
(<a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S");
<LI>size of string buffer used by 
<a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S".
</UL>


<hr>
<A name=11.4.1.2>
<H4>11.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI>attempting to position a file outside its boundaries
(<a href=dpans11.htm#11.6.1.2142>11.6.1.2142</a> REPOSITION-FILE);
<LI>attempting to read from file positions not yet written
(<a href=dpans11.htm#11.6.1.2080>11.6.1.2080</a> READ-FILE, 
<a href=dpans11.htm#11.6.1.2090>11.6.1.2090</a> READ-LINE);
<LI>fileid is invalid 
(<a href=dpans11.htm#11.6.1.1717>11.6.1.1717</a> INCLUDE-FILE);
<LI>I/O exception reading or closing fileid 
(<a href=dpans11.htm#11.6.1.1717>11.6.1.1717</a> INCLUDE-FILE, 
<a href=dpans11.htm#11.6.1.1718>11.6.1.1718</a> INCLUDED);
<LI>named file cannot be opened 
(<a href=dpans11.htm#11.6.1.1718>11.6.1.1718</a> INCLUDED);
<LI>requesting an unmapped block number 
(<a href=dpans11.htm#11.3.2>11.3.2</a> Blocks in files);
<LI>using 
<a href=dpans11.htm#11.6.1.2218>11.6.1.2218</a> SOURCE-ID when 
<a href=dpans7.htm#7.6.1.0790>7.6.1.0790</a> BLK is not zero.
</ul>

<hr>
<A name=11.4.3>
<h4>11.4.1.3 Other system documentation</h4>
</a>
<ul>
<LI>no additional requirements.
</UL>

<hr>
<A name=11.4.2>
<H3>11.4.2 Program documentation</H3>
</a>


<hr>
<A name=11.4.2.1>
<H4>11.4.2.1 Environmental dependencies</H4>
</a>

<UL>
<LI>requiring lines longer than 128 characters 
(<a href=dpans11.htm#11.3.6>11.3.6</a> Parsing);
<LI>using more than eight levels of input-file nesting 
(<a href=dpans11.htm#11.3.4>11.3.4</a> Input source).
</UL>

<P>

<hr>
<A name=11.4.2.2>
<H4>11.4.2.2 Other program documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</ul>


<hr>
<A name=11.5>
<h2>11.5 Compliance and labeling</h2>
</a>


<hr>
<A name=11.5.1>
<H3>11.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the File Access word set</B> shall be appended
to the label of any Standard System that provides all of the File Access
word set.

<P>

The phrase <B>Providing name(s) from the File Access Extensions word
set</B> shall be appended to the label of any Standard System that
provides portions of the File Access Extensions word set.

<P>

The phrase <B>Providing the File Access Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
File Access and File Access Extensions word sets.


<P>

<hr>
<A name=11.5.2>
<H3>11.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the File Access word set</B> shall be appended
to the label of Standard Programs that require the system to provide the
File Access word set.

<P>

The phrase <B>Requiring name(s) from the File Access Extensions word
set</B> shall be appended to the label of Standard Programs that require
the system to provide portions of the File Access Extensions word set.

<P>

The phrase <B>Requiring the File Access Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the File Access and File Access Extensions word sets.

<P>

<hr>
<A name=11.6>
<H2>11.6 Glossary</H2>
</a>


<hr>
<A name=11.6.1>
<H3>11.6.1 File Access words</H3>
</a>


<hr>
<A name=11.6.1.0080>
<code>
11.6.1.0080 <b>(</b>
</code>
</a>
<BR>
<B>paren</B> FILE
<BR>
<pre>
	( <B>"ccc&lt;paren&gt;"</B> -- )
</pre>
<P>

Extend the semantics of 
<A href=dpans6.htm#6.1.0080>6.1.0080</a> ( to include:
<P>

When parsing from a text file, if the end of the parse area is reached
before a right parenthesis is found, refill the input buffer from the
next line of the file, set 
<A href=dpans6.htm#6.1.0560>&gt;IN</a> 
to zero, and resume parsing, repeating
this process until either a right parenthesis is found or the end of the
file is reached.

<P>

<hr>
<A name=11.6.1.0765>
<code>
11.6.1.0765 <b>BIN</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( fam1 -- fam2 )
</pre>
<P>

Modify the implementation-defined file access method fam1 to
additionally select a <B>binary</B>, i.e., not line oriented, file
access method, giving access method fam2.
<p>

<code>
See:    
<a href=dpansa11.htm#A.11.6.1.0765>A.11.6.1.0765 BIN</a> ,
<A href=dpans11.htm#11.6.1.2054>11.6.1.2054 R/O</a> ,
<A href=dpans11.htm#11.6.1.2056>11.6.1.2056 R/W</a> ,
<A href=dpans11.htm#11.6.1.2425>11.6.1.2425 W/O</a>
</code>

<P>

<hr>
<A name=11.6.1.0900>
<code>
11.6.1.0900 <b>CLOSE-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( fileid -- ior )
</pre>
<P>

Close the file identified by fileid.  ior is the implementation-defined
I/O result code.

<P>

<hr>
<A name=11.6.1.1010>
<code>
11.6.1.1010 <b>CREATE-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u fam -- fileid ior )
</pre>
<P>

Create the file named in the character string specified by c-addr and u,
and open it with file access method fam.  The meaning of values of fam
is implementation defined.  If a file with the same name already exists,
recreate it as an empty file.

<P>

If the file was successfully created and opened, ior is zero, fileid is
its identifier, and the file has been positioned to the start of the
file.

<P>

Otherwise, ior is the implementation-defined I/O result code and fileid
is undefined.

<p>
<code>
See:
<a href=dpansa11.htm#A.11.6.1.1010>A.11.6.1.1010 CREATE-FILE</a>
</code>
<p>


<hr>
<A name=11.6.1.1190>
<code>
11.6.1.1190 <b>DELETE-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u -- ior )
</pre>
<P>

Delete the file named in the character string specified by c-addr u.
ior is the implementation-defined I/O result code.

<P>

<hr>
<A name=11.6.1.1520>
<code>
11.6.1.1520 <b>FILE-POSITION</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( fileid -- ud ior )
</pre>
<P>

ud is the current file position for the file identified by fileid.  ior
is the implementation-defined I/O result code.  ud is undefined if ior
is non-zero.

<P>

<hr>
<A name=11.6.1.1522>
<code>
11.6.1.1522 <b>FILE-SIZE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( fileid -- ud ior )
</pre>
<P>

ud is the size, in characters, of the file identified by fileid.  ior is
the implementation-defined I/O result code.  This operation does not
affect the value returned by 
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>.  
ud is undefined if ior is
non-zero.

<P>

<hr>
<A name=11.6.1.1717>
<code>
11.6.1.1717 <b>INCLUDE-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( i*x fileid -- j*x )
</pre>
<P>

Remove fileid from the stack.  Save the current input source
specification, including the current value of 
<A href=dpans6.htm#6.2.2218>SOURCE-ID</a>.  Store fileid
in SOURCE-ID.  Make the file specified by fileid the input source.
Store zero in 
<A href=dpans7.htm#7.6.1.0790>BLK</a>.  
Other stack effects are due to the words included.

<P>

Repeat until end of file: read a line from the file, fill the input
buffer from the contents of that line, set 
<A href=dpans6.htm#6.1.0560>&gt;IN</a> to zero, and interpret.

<P>

Text interpretation begins at the file position where the next file read
would occur.

<P>

When the end of the file is reached, close the file and restore the
input source specification to its saved value.

<P>

An ambiguous condition exists if fileid is invalid, if there is an I/O
exception reading fileid, or if an I/O exception occurs while closing
fileid.  When an ambiguous condition exists, the status (open or closed)
of any files that were being interpreted is implementation-defined.
<P>

<code>
See:
<A href=dpans11.htm#11.3.4>11.3.4</a> Input source,
<a href=dpansa11.htm#A.11.6.1.1717>A.11.6.1.1717 INCLUDE-FILE</a>
</code>
<p>


<hr>
<A name=11.6.1.1718>
<code>
11.6.1.1718 <b>INCLUDED</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( i*x c-addr u -- j*x )
</pre>
<P>

Remove c-addr u from the stack.  Save the current input source
specification, including the current value of 
<A href=dpans6.htm#6.2.2218>SOURCE-ID</a>.  Open the file
specified by c-addr u, store the resulting fileid in SOURCE-ID, and make
it the input source.  Store zero in 
<A href=dpans7.htm#7.6.1.0790>BLK</a>.  Other stack effects are due to
the words included.

<P>

Repeat until end of file: read a line from the file, fill the input
buffer from the contents of that line, set 
<A href=dpans6.htm#6.1.0560>&gt;IN</a> to zero, and interpret.

<P>

Text interpretation begins at the file position where the next file read
would occur.

<P>

When the end of the file is reached, close the file and restore the
input source specification to its saved value.

<P>

An ambiguous condition exists if the named file can not be opened, if an
I/O exception occurs reading the file, or if an I/O exception occurs
while closing the file.  When an ambiguous condition exists, the status
(open or closed) of any files that were being interpreted is
implementation-defined.

<P>

<code>
See:    
<a href=dpansa11.htm#A.11.6.1.1718>A.11.6.1.1718 INCLUDED</a> ,
<A href=dpans11.htm#11.6.1.1717>11.6.1.1717 INCLUDE-FILE</a>
</code>

<P>

<hr>
<A name=11.6.1.1970>
<code>
11.6.1.1970 <b>OPEN-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u fam -- fileid ior )
</pre>
<P>

Open the file named in the character string specified by c-addr u, with
file access method indicated by fam.  The meaning of values of fam is
implementation defined.

<P>

If the file is successfully opened, ior is zero, fileid is its
identifier, and the file has been positioned to the start of the file.

<P>

Otherwise, ior is the implementation-defined I/O result code and fileid
is undefined.

<p>
<code>
See:
<a href=dpansa11.htm#A.11.6.1.1970>A.11.6.1.1970 OPEN-FILE</a>
</code>
<p>


<hr>
<A name=11.6.1.2054>
<code>
11.6.1.2054 <b>R/O</b>
</code>
</a>
<BR>
<B>r-o</B>   FILE
<BR>
<pre>
	( -- fam )
</pre>
<P>

fam is the implementation-defined value for selecting the <B>read
only</B> file access method.
<p>

<code>
See:    
<A href=dpans11.htm#11.6.1.1010>11.6.1.1010 CREATE-FILE</a> ,
<A href=dpans11.htm#11.6.1.1970>11.6.1.1970 OPEN-FILE</a>
</code>

<P>

<hr>
<A name=11.6.1.2056>
<code>
11.6.1.2056 <b>R/W</b>
</code>
</a>
<BR>
<B>r-w</B>   FILE
<BR>
<pre>
	( -- fam )
</pre>
<P>

fam is the implementation-defined value for selecting the
<B>read/write</B> file access method.
<p>

<code>
See:    
<A href=dpans11.htm#11.6.1.1010>11.6.1.1010 CREATE-FILE</a> ,
<A href=dpans11.htm#11.6.1.1970>11.6.1.1970 OPEN-FILE</a>
</code>

<P>

<hr>
<A name=11.6.1.2080>
<code>
11.6.1.2080 <b>READ-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u1 fileid -- u2 ior )
</pre>
<P>

Read u1 consecutive characters to c-addr from the current position of
the file identified by fileid.

<P>

If u1 characters are read without an exception, ior is zero and u2 is
equal to u1.

<P>

If the end of the file is reached before u1 characters are read, ior is
zero and u2 is the number of characters actually read.

<P>

If the operation is initiated when the value returned by 
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>
is equal to the value returned by 
<A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> for the file identified by
fileid, ior is zero and u2 is zero.

<P>

If an exception occurs, ior is the implementation-defined I/O result
code, and u2 is the number of characters transferred to c-addr without
an exception.

<P>

An ambiguous condition exists if the operation is initiated when the
value returned by FILE-POSITION is greater than the value returned by
FILE-SIZE for the file identified by fileid, or if the requested
operation attempts to read portions of the file not written.

<P>

At the conclusion of the operation, FILE-POSITION returns the next file
position after the last character read.

<p>
<code>
See:
<a href=dpansa11.htm#A.11.6.1.2080>A.11.6.1.2080 READ-FILE</a>
</code>
<p>


<hr>
<A name=11.6.1.2090>
<code>
11.6.1.2090 <b>READ-LINE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u1 fileid -- u2 flag ior )
</pre>
<P>

Read the next line from the file specified by fileid into memory at the
address c-addr.  At most u1 characters are read.  Up to two
implementation-defined line-terminating characters may be read into
memory at the end of the line, but are not included in the count u2.
The line buffer provided by c-addr should be at least u1+2 characters
long.

<P>

If the operation succeeded, flag is true and ior is zero.  If a line
terminator was received before u1 characters were read, then u2 is the
number of characters, not including the line terminator, actually read
(0 &lt;= u2 &lt;= u1).  When u1 = u2, the line terminator has yet to be
reached.

<P>

If the operation is initiated when the value returned by 
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>
is equal to the value returned by 
<A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> for the file identified by
fileid, flag is false, ior is zero, and u2 is zero.  If ior is non-zero,
an exception occurred during the operation and ior is the
implementation-defined I/O result code.

<P>

An ambiguous condition exists if the operation is initiated when the
value returned by FILE-POSITION is greater than the value returned by
FILE-SIZE for the file identified by fileid, or if the requested
operation attempts to read portions of the file not written.

<P>

At the conclusion of the operation, FILE-POSITION returns the next file
position after the last character read.

<p>
<code>
See:
<a href=dpansa11.htm#A.11.6.1.2090>A.11.6.1.2090 READ-LINE</a> ,
<a href=a0001.htm>RFI 0001</a>.
</code>
<p>


<hr>
<A name=11.6.1.2142>
<code>
11.6.1.2142 <b>REPOSITION-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( ud fileid -- ior )
</pre>
<P>

Reposition the file identified by fileid to ud.  ior is the
implementation-defined I/O result code.  An ambiguous condition exists
if the file is positioned outside the file boundaries.

<P>

At the conclusion of the operation, 
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> returns the
value ud.

<P>

<hr>
<A name=11.6.1.2147>
<code>
11.6.1.2147 <b>RESIZE-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( ud fileid -- ior )
</pre>
<P>

Set the size of the file identified by fileid to ud.  ior is the
implementation-defined I/O result code.

<P>

If the resultant file is larger than the file before the operation, the
portion of the file added as a result of the operation might not have
been written.

<P>

At the conclusion of the operation, 
<A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a> returns the value ud and
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> 
returns an unspecified value.
<p>

<code>
See:    
<A href=dpans11.htm#11.6.1.2080>11.6.1.2080 READ-FILE</a> ,
<A href=dpans11.htm#11.6.1.2090>11.6.1.2090 READ-LINE</a>
</code>

<P>

<hr>
<A name=11.6.1.2165>
<code>
11.6.1.2165 <b>S"</b>
</code>
</a>
<BR>
<B>s-quote</B>       FILE
<BR>
<P>

Extend the semantics of 
<A href=dpans6.htm#6.1.2165>6.1.2165</a> S" to be:

<PRE>
        Interpretation: ( <B>"ccc&lt;quote&gt;"</B> -- c-addr u )
</PRE>
<P>

Parse ccc delimited by " (double quote).  Store the resulting string
c-addr u at a temporary location.  The maximum length of the temporary
buffer is implementation-dependent but shall be no less than 80
characters.  Subsequent uses of S" may overwrite the temporary buffer.
At least one such buffer shall be provided.


<PRE>
        Compilation: ( <B>"ccc&lt;quote&gt;"</B> -- )
</PRE>

<P>

Parse ccc delimited by " (double quote).  Append the run-time semantics
given below to the current definition.

<PRE>
        Run-time: ( -- c-addr u )
</PRE>
<P>

Return c-addr and u that describe a string consisting of the characters
ccc.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.2.0855>6.2.0855 C"</a> ,
<a href=dpansa11.htm#A.11.6.1.2165>A.11.6.1.2165 S"</a> ,
<A href=dpans11.htm#11.3.5>11.3.5</a> Other transient regions.
</code>

<P>

<hr>
<A name=11.6.1.2218>
<code>
11.6.1.2218 <b>SOURCE-ID</b>
</code>
</a>
<BR>
<B>source-i-d</B>    FILE
<BR>
<pre>
	( -- 0 | -1 | fileid )
</pre>
<P>

Extend 
<A href=dpans6.htm#6.2.2218>6.2.2218</a> 
SOURCE-ID to include text-file input as follows:


<PRE>
SOURCE-ID       Input source
---------       ------------
fileid          Text file <B>fileid</B>
-1              String (via <A href=dpans6.htm#6.1.1360>EVALUATE</a>)
0               User input device
</PRE>
<P>

An ambiguous condition exists if SOURCE-ID is used when 
<A href=dpans7.htm#7.6.1.0790>BLK</a> contains a
non-zero value.

<P>

<hr>
<A name=11.6.1.2425>
<code>
11.6.1.2425 <b>W/O</b>
</code>
</a>
<BR>
<B>w-o</B>   FILE
<BR>
<pre>
	( -- fam )
</pre>
<P>

fam is the implementation-defined value for selecting the <B>write
only</B> file access method.
<p>

<code>
See:    
<A href=dpans11.htm#11.6.1.1010>11.6.1.1010 CREATE-FILE</a> ,
<A href=dpans11.htm#11.6.1.1970>11.6.1.1970 OPEN-FILE</a>
</code>

<P>

<hr>
<A name=11.6.1.2480>
<code>
11.6.1.2480 <b>WRITE-FILE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u fileid -- ior )
</pre>
<P>

Write u characters from c-addr to the file identified by fileid starting
at its current position.  ior is the implementation-defined I/O result
code.

<P>

At the conclusion of the operation, 
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> returns the next file
position after the last character written to the file, and 
<A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a>
returns a value greater than or equal to the value returned by
FILE-POSITION.
<p>

<code>
See:    
<A href=dpans11.htm#11.6.1.2080>11.6.1.2080 READ-FILE</a> ,
<A href=dpans11.htm#11.6.1.2090>11.6.1.2090 READ-LINE</a>
</code>

<P>

<hr>
<A name=11.6.1.2485>
<code>
11.6.1.2485 <b>WRITE-LINE</b>
</code>
</a>
<BR>
FILE
<BR>
<pre>
	( c-addr u fileid -- ior )
</pre>
<P>

Write u characters from c-addr followed by the implementation-dependent
line terminator to the file identified by fileid starting at its current
position.  ior is the implementation-defined I/O result code.

<P>

At the conclusion of the operation, 
<A href=dpans11.htm#11.6.1.1520>FILE-POSITION</a> returns the next file
position after the last character written to the file, and 
<A href=dpans11.htm#11.6.1.1522>FILE-SIZE</a>
returns a value greater than or equal to the value returned by
FILE-POSITION.
<p>

<code>
See:    
<A href=dpans11.htm#11.6.1.2080>11.6.1.2080 READ-FILE</a> ,
<A href=dpans11.htm#11.6.1.2090>11.6.1.2090 READ-LINE</a>
</code>

<P>

<hr>
<a name=11.6.2>
<H3>11.6.2 File-Access extension words</H3>
</a>


<hr>
<A name=11.6.2.1524>
<code>
11.6.2.1524 <b>FILE-STATUS</b>
</code>
</a>
<BR>
FILE EXT
<BR>
<pre>
	( c-addr u -- x ior )
</pre>
<P>

Return the status of the file identified by the character string c-addr
u.  If the file exists, ior is zero; otherwise ior is the
implementation-defined I/O result code.  x contains
implementation-defined information about the file.

<P>

<hr>
<A name=11.6.2.1560>
<code>
11.6.2.1560 <b>FLUSH-FILE</b>
</code>
</a>
<BR>
FILE EXT
<BR>
<pre>
	( fileid -- ior )
</pre>
<P>

Attempt to force any buffered information written to the file referred
to by fileid to be written to mass storage, and the size information for
the file to be recorded in the storage directory if changed.  If the
operation is successful, ior is zero.  Otherwise, it is an
implementation-defined I/O result code.


<P>

<hr>
<A name=11.6.2.2125>
<code>
11.6.2.2125 <b>REFILL</b>
</code>
</a>
<BR>
FILE EXT
<BR>
<pre>
	( -- flag )
</pre>
<P>

Extend the execution semantics of 
<A href=dpans6.htm#6.2.2125>6.2.2125</a> REFILL with the
following:

<P>

When the input source is a text file, attempt to read the next line from
the text-input file.  If successful, make the result the current input
buffer, set 
<A href=dpans6.htm#6.1.0560>&gt;IN</a> 
to zero, and return true.  Otherwise return false.
<P>

<code>
See:    
<A href=dpans7.htm#7.6.2.2125>7.6.2.2125 REFILL</a>
</code>
<P>

<hr>
<A name=11.6.2.2130>
<code>
11.6.2.2130 <b>RENAME-FILE</b>
</code>
</a>
<BR>
FILE EXT
<BR>
<pre>
	( c-addr1 u1 c-addr2 u2 -- ior )
</pre>
<P>

Rename the file named by the character string c-addr1 u1 to the name in
the character string c-addr2 u2.  ior is the implementation-defined I/O
result code.


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans12.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>


dpans12.htm/    851247240   500   0     100644  40214     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans11.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans13.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=12.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>12. The optional Floating-Point word set</H1>

<hr>
<A name=12.1>
<H2>12.1 Introduction</H2>
</a>

<p>
<code>
See:
<a href=dpansa12.htm#A.12>A.12</a> The optional Floating-Point word set
</code>
<p>

<hr>
<A name=12.2>
<H2>12.2 Additional terms and notation</H2>
</a>


<hr>
<A name=12.2.1>
<H3>12.2.1 Definition of terms</H3>
</a>


<DL>
<DT><B>float-aligned address:</B>
<DD>The address of a memory location at which a
floating-point number can be accessed.

<DT><B>double-float-aligned address:</B>
<DD>The address of a memory location at which
a 64-bit IEEE double-precision floating-point number can be accessed.

<DT><B>single-float-aligned address:</B>
<DD>The address of a memory location at which
a 32-bit IEEE single-precision floating-point number can be accessed.

<DT><B>IEEE floating-point number:</B>
<DD>A single- or double-precision floating-point
number as defined in ANSI/IEEE 754-1985.</DL>


<P>

<hr>
<A name=12.2.2>
<H3>12.2.2 Notation</H3>
</a>


<hr>
<A name=12.2.2.1>
<H4>12.2.2.1 Numeric notation</H4>
</a>

The following notation is used to define the syntax of the external
representation of floating-point numbers:

<UL>
<LI>Each component of a floating-point number is defined with a rule
consisting of the name of the component (italicized in angle-brackets,
e.g.,<I>&lt;sign&gt;</I> characters := and a concatenation of tokens and
metacharacters;
<LI>Tokens may be literal characters (in bold face, e.g.,<B>E</B>) or rule
names in angle brackets (e.g.,&lt;digit&gt;);
<LI>The metacharacter * is used to specify zero or more occurrences
of the preceding token (e.g.,&lt;digit&gt;*);
<LI>Tokens enclosed with [ and ] are optional (e.g.,[&lt;sign&gt;]);
<LI>Vertical bars separate choices from a list of tokens enclosed
with braces (e.g.,{ + | - }).
</UL>

<P>

<hr>
<A name=12.2.2.2>
<H4>12.2.2.2 Stack notation</H4>
</a>

Floating-point stack notation when the floating-point stack is separate
from the data stack is:
<P>

( F:  before -- after )
<P>


<hr>
<A name=12.3>
<H2>12.3 Additional usage requirements</H2>
</a>


<hr>
<A name=12.3.1>
<H3>12.3.1 Data types</H3>
</a>

Append table 12.1 to
<a href=dpans3.htm#table.3.1>table 3.1</a>.

<P>

Table 12.1 - Data Types
<P>



<PRE>
Symbol    Data type                       Size on stack
------    ---------                       -------------
r         floating-point number           implementation-defined
f-addr    float-aligned address           1 cell
sf-addr   single-float-aligned address    1 cell
df-addr   double-float-aligned address    1 cell
</PRE>


<P>

<hr>
<A name=12.3.1.1>
<H4>12.3.1.1 Addresses</H4>
</a>

The set of float-aligned addresses is an implementation-defined subset
of the set of aligned addresses.  Adding the size of a floating-point
number to a float-aligned address shall produce a float-aligned address.

<P>

The set of double-float-aligned addresses is an implementation-defined
subset of the set of aligned addresses.  Adding the size of a 64-bit
IEEE double-precision floating-point number to a double-float-aligned
address shall produce a double-float-aligned address.

<P>

The set of single-float-aligned addresses is an implementation-defined
subset of the set of aligned addresses.  Adding the size of a 32-bit
IEEE single-precision floating-point number to a single-float-aligned
address shall produce a single-float-aligned address.

<P>

<hr>
<A name=12.3.1.2>
<H4>12.3.1.2 Floating-point numbers</H4>
</a>

The internal representation of a floating-point number, including the
format and precision of the significand and the format and range of the
exponent, is implementation defined.

<P>

Any rounding or truncation of floating-point numbers is implementation
defined.

<P>

<hr>
<A name=12.3.2>
<H3>12.3.2 Floating-point operations</H3>
</a>

<B>Round to nearest</B> means round the result of a floating-point
operation to the representable value nearest the result.  If the two
nearest representable values are equally near the result, the one having
zero as its least significant bit shall be delivered.

<P>

<B>Round toward negative infinity</B> means round the result of a
floating-point operation to the representable value nearest to and no
greater than the result.

<P>

<hr>
<A name=12.3.3>
<H3>12.3.3 Floating-point stack</H3>
</a>

A last in, first out list that shall be used by all floating-point
operators.

<P>

The width of the floating-point stack is implementation-defined.  By
default the floating-point stack shall be separate from the data and
return stacks.  A program may determine whether floating-point numbers
are kept on the data stack by passing the string 
<a href=dpans12.htm#12.3.4>FLOATING-STACK</a>
to 
<a href=dpans6.htm#6.1.1345>ENVIRONMENT?</a>.

<P>

The size
of a floating-point stack shall be at least 6 items.

<P>

A program that depends on the floating-point stack being larger than six
items has an environmental dependency.

<P>

<hr>
<A name=12.3.4>
<H3>12.3.4 Environmental queries</H3>
</a>

Append table 12.2 to
table 3.5.

<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 12.2 - Environmental query strings
<P>



<PRE>
String          Value data type  Constant?  Meaning
------          ---------------  ---------  -------
FLOATING        flag             no         floating-point word set present
FLOATING-EXT    flag             no         floating-point extensions word set present
FLOATING-STACK  n                yes        If n = zero, floating-point numbers are 
                                            kept on the data stack; otherwise n is 
                                            the maximum depth of the separate 
                                            floating-point stack.
MAX-FLOAT       r                yes        largest usable floating-point number

</PRE>

<P>

<hr>
<A name=12.3.5>
<H3>12.3.5 Address alignment</H3>
</a>

Since the address returned by a 
<a href=dpans6.htm#6.1.1000>CREATE</a>d word is not necessarily aligned
for any particular class of floating-point data, a program shall align
the address (to be float aligned, single-float aligned, or double-float
aligned) before accessing floating-point data at the address.

<P>

<code>
See:  
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment,
<a href=dpansa12.htm#A.12.3.5>A.12.3.5</a> Address alignment,
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses.
</code>
<P>

<hr>
<A name=12.3.6>
<H3>12.3.6 Variables</H3>
</a>

A program may address memory in data space regions made available by
<a href=dpans12.htm#12.6.1.1630>FVARIABLE</a>.  
These regions may be non-contiguous with regions
subsequently allocated with , 
(<a href=dpans6.htm#6.1.0150>comma</a>) or 
<a href=dpans6.htm#6.1.0710>ALLOT</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.3>3.3.3.3</a> Variables
</code>
<P>


<hr>
<A name=12.3.7>
<H3>12.3.7 Text interpreter input number conversion</H3>
</a>

If the Floating-Point word set is present in the dictionary and the
current base is 
<a href=dpans6.htm#6.1.1170>DECIMAL</a>, 
the input number-conversion algorithm shall be
extended to recognize floating-point numbers in this form:

<P>

Convertible string := &lt;significand&gt;&lt;exponent&gt;


<PRE>
&lt;significand&gt; := [&lt;sign&gt;]&lt;digits&gt;[.&lt;digits0&gt;]
&lt;exponent&gt;    := E[&lt;sign&gt;]&lt;digits0&gt;
&lt;sign&gt;        := { + | - }
&lt;digits&gt;      := &lt;digit&gt;&lt;digits0&gt;
&lt;digits0&gt;     := &lt;digit&gt;*
&lt;digit&gt;       := { 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }
</PRE>
<P>

These are examples of valid representations of floating-point numbers in
program source:

<PRE>
	1E   1.E   1.E0   +1.23E-1   -1.23E+1
</PRE>
<P>

<code>
See:
<A href=dpans3.htm#3.4.1.3>3.4.1.3</a> Text interpreter input number
conversion,
<a href=dpansa12.htm#A.12.3.7>A.12.3.7</a> Text interpreter input number conversion,
<A href=dpans12.htm#12.6.1.0558>12.6.1.0558 &gt;FLOAT</a>
</code>

<P>

<hr>
<A name=12.4>
<H2>12.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=12.4.1>
<H3>12.4.1 System documentation</H3>
</a>


<hr>
<A name=12.4.1.1>
<H4>12.4.1.1 Implementation-defined options</H4>
</a>


<UL>
<LI>format and range of floating-point numbers 
(<a href=dpans12.htm#12.3.1>12.3.1</a> Data types,
<a href=dpans12.htm#12.6.1.2143>12.6.1.2143</a> REPRESENT);
<LI>results of 
<a href=dpans12.htm#12.6.1.2143>12.6.1.2143</a> REPRESENT 
when float is out of range;
<LI>rounding or truncation of floating-point numbers 
(<a href=dpans12.htm#12.3.1.2>12.3.1.2</a>
Floating-point numbers);
<LI>size of floating-point stack 
(<a href=dpans12.htm#12.3.3>12.3.3</a> Floating-point stack);
<LI>width of floating-point stack 
(<a href=dpans12.htm#12.3.3>12.3.3</a> Floating-point stack).
</UL>

<P>

<hr>
<A name=12.4.1.2>
<H4>12.4.1.2 Ambiguous conditions</H4>
</a>
<P>

<UL>
<LI>
<a href=dpans12.htm#12.6.2.1204>DF@</a> or 
<a href=dpans12.htm#12.6.2.1203>DF!</a> is 
used with an address that is not double-float aligned;
<LI>
<a href=dpans12.htm#12.6.1.1472>F@</a> or 
<a href=dpans12.htm#12.6.1.1400>F!</a> is 
used with an address that is not float aligned;
<LI>FLOATing point result out of range (e.g., in 
<a href=dpans12.htm#12.6.1.1430>12.6.1.1430</a> F/);
<LI>
<a href=dpans12.htm#12.6.2.2203>SF@</a> or 
<a href=dpans12.htm#12.6.2.2202>SF!</a> is 
used with an address that is not single-float aligned;
<LI>
<a href=dpans6.htm#6.1.0750>BASE</a> is not decimal 
(<a href=dpans12.htm#12.6.1.2143>12.6.1.2143</a> REPRESENT, 
<a href=dpans12.htm#12.6.2.1427>12.6.2.1427</a> F.,
<a href=dpans12.htm#12.6.2.1513>12.6.2.1513</a> FE., 
<a href=dpans12.htm#12.6.2.1613>12.6.2.1613</a> FS.);
<LI>both arguments equal zero 
(<a href=dpans12.htm#12.6.2.1489>12.6.2.1489</a> FATAN2);
<LI>cosine of argument is zero for 
<a href=dpans12.htm#12.6.2.1625>12.6.2.1625</a> FTAN;
<LI>d can't be precisely represented as float in 
<a href=dpans12.htm#12.6.1.1130>12.6.1.1130</a> D>F;
<LI>dividing by zero 
(<a href=dpans12.htm#12.6.1.1430>12.6.1.1430</a> F/);
<LI>exponent too big for conversion 
(<a href=dpans12.htm#12.6.2.1203>12.6.2.1203</a> DF!, 
<a href=dpans12.htm#12.6.2.1204>12.6.2.1204</a> DF@,
<a href=dpans12.htm#12.6.2.2202>12.6.2.2202</a> SF!, 
<a href=dpans12.htm#12.6.2.2203>12.6.2.2203</a> SF@);
<LI>FLOAT less than one 
(<a href=dpans12.htm#12.6.2.1477>12.6.2.1477</a> FACOSH);
<LI>FLOAT less than or equal to minus-one 
(<a href=dpans12.htm#12.6.2.1554>12.6.2.1554</a> FLNP1);
<LI>FLOAT less than or equal to zero 
(<a href=dpans12.htm#12.6.2.1553>12.6.2.1553</a> FLN, 
<a href=dpans12.htm#12.6.2.1557>12.6.2.1557</a> FLOG);
<LI>FLOAT less than zero 
(<a href=dpans12.htm#12.6.2.1487>12.6.2.1487</a> FASINH, 
<a href=dpans12.htm#12.6.2.1618>12.6.2.1618</a> FSQRT);
<LI>FLOAT magnitude greater than one 
(<a href=dpans12.htm#12.6.2.1476>12.6.2.1476</a> FACOS, 
<a href=dpans12.htm#12.6.2.1486>12.6.2.1486</a> FASIN, 
<a href=dpans12.htm#12.6.2.1491>12.6.2.1491</a> FATANH);
<LI>Integer part of float can't be represented by d in 
<a href=dpans12.htm#12.6.1.1470>12.6.1.1470</a> F>D;
<LI>string larger than pictured-numeric output area 
(<a href=dpans12.htm#12.6.2.1427>12.6.2.1427</a> F.,
<a href=dpans12.htm#12.6.2.1513>12.6.2.1513</a> FE., 
<a href=dpans12.htm#12.6.2.1613>12.6.2.1613</a> FS.).
</UL>

<P>

<hr>
<A name=12.4.1.3>
<H4>12.4.1.3 Other system documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>

<hr>
<A name=12.4.2>
<H3>12.4.2 Program documentation</H3>
</a>


<hr>
<A name=12.4.2.1>
<H4>12.4.2.1 Environmental dependencies</H4>
</a>

<UL>
<LI>requiring the floating-point stack to be larger than six items 
(<a href=dpans12.htm#12.3.3>12.3.3</a> Floating-point stack).
</UL>

<P>

<hr>
<A name=12.4.2.2>
<H4>12.4.2.2 Other program documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>

<P>

<hr>
<A name=12.5>
<H2>12.5 Compliance and labeling</H2>
</a>


<hr>
<A name=12.5.1>
<H3>12.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Floating-Point word set</B> shall be
appended to the label of any Standard System that provides all of the
Floating-Point word set.

<P>

The phrase <B>Providing name(s) from the Floating-Point Extensions word
set</B> shall be appended to the label of any Standard System that
provides portions of the Floating-Point Extensions word set.

<P>

The phrase <B>Providing the Floating-Point Extensions word set</B> shall
be appended to the label of any Standard System that provides all of the
Floating-Point and Floating-Point Extensions word sets.

<P>

<hr>
<A name=12.5.2>
<H3>12.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Floating-Point word set</B> shall be
appended to the label of Standard Programs that require the system to
provide the Floating-Point word set.

<P>

The phrase <B>Requiring name(s) from the Floating-Point Extensions word
set</B> shall be appended to the label of Standard Programs that require
the system to provide portions of the Floating-Point Extensions word
set.

<P>

The phrase <B>Requiring the Floating-Point Extensions word set</B> shall
be appended to the label of Standard Programs that require the system to
provide all of the Floating-Point and Floating-Point Extensions word
sets.

<P>

<hr>
<A name=12.6>
<H2>12.6 Glossary</H2>
</a>


<hr>
<A name=12.6.1>
<H3>12.6.1 Floating-Point words</H3>
</a>



<hr>
<A name=12.6.1.0558>
<code>
12.6.1.0558 <b>&gt;FLOAT</b>
</code>
</a>
<BR>
<B>to-float</B>      FLOATING
<BR>
<pre>
	( c-addr u -- true | false ) ( F: -- r |  )  
	or ( c-addr u -- r true | false)
</pre>

<P>

An attempt is made to convert the string specified by c-addr and u to
internal floating-point representation.  If the string represents a
valid floating-point number in the syntax below, its value r and true
are returned.  If the string does not represent a valid floating-point
number only false is returned.

<P>

A string of blanks should be treated as a special case representing
zero.

<P>

The syntax of a convertible string := &lt;significand&gt;[&lt;exponent&gt;]

<PRE>
&lt;significand&gt; := [&lt;sign&gt;]{&lt;digits&gt;[.&lt;digits0&gt;] |
.&lt;digits&gt; }
&lt;exponent&gt;    := &lt;marker&gt;&lt;digits0&gt;
&lt;marker&gt;      := {&lt;e-form&gt; | &lt;sign-form&gt;}
&lt;e-form&gt;      := &lt;e-char&gt;[&lt;sign-form&gt;]
&lt;sign-form&gt;   := { + | - }
&lt;e-char&gt;      := { D | d | E | e }
</PRE>

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.1.0558>A.12.6.1.0558 &gt;FLOAT</a>
</code>
<p>


<hr>
<A name=12.6.1.1130>
<code>
12.6.1.1130 <b>D&gt;F</b>
</code>
</a>
<BR>
<B>d-to-f</B>        FLOATING
<BR>
<pre>
	( d -- ) ( F: -- r ) 
        or ( d -- r )
</pre>

<P>

r is the floating-point equivalent of d.  An ambiguous condition exists
if d cannot be precisely represented as a floating-point value.

<P>

<hr>
<A name=12.6.1.1400>
<code>
12.6.1.1400 <b>F!</b>
</code>
</a>
<BR>
<B>f-store</B>       FLOATING
<BR>
<pre>
	( f-addr -- ) ( F: r -- ) 
        or ( r f-addr -- )
</pre>

<P>

Store r at
f-addr.

<P>

<hr>
<A name=12.6.1.1410>
<code>
12.6.1.1410 <b>F*</b>
</code>
</a>
<BR>
<B>f-star</B>        FLOATING
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

Multiply r1
by r2 giving r3.

<P>

<hr>
<A name=12.6.1.1420>
<code>
12.6.1.1420 <b>F+</b>
</code>
</a>
<BR>
<B>f-plus</B>        FLOATING
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

Add r1 to r2
giving the sum r3.

<P>

<hr>
<A name=12.6.1.1425>
<code>
12.6.1.1425 <b>F-</b>
</code>
</a>
<BR>
<B>f-minus</B>       FLOATING
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

Subtract r2 from r1,
giving r3.

<P>

<hr>
<A name=12.6.1.1430>
<code>
12.6.1.1430 <b>F/</b>
</code>
</a>
<BR>
<B>f-slash</B>       FLOATING
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

Divide r1 by r2, giving the quotient r3.  An ambiguous condition exists
if r2 is zero, or the quotient lies outside of the range of a
floating-point number.

<P>

<hr>
<A name=12.6.1.1440>
<code>
12.6.1.1440 <b>F0<</b>
</code>
</a>
<BR>
<B>f-zero-less-than</B>      FLOATING
<BR>
<pre>
	( -- flag ) ( F: r -- ) 
	or ( r -- flag )
</pre>

<P>

flag is true
if and only if r is less than zero.

<P>

<hr>
<A name=12.6.1.1450>
<code>
12.6.1.1450 <b>F0=</b>
</code>
</a>
<BR>
<B>f-zero-equals</B> FLOATING
<BR>
<pre>
	( -- flag ) ( F: r -- ) 
	or ( r -- flag )
</pre>

<P>

flag is true
if and only if r is equal to zero.

<P>

<hr>
<A name=12.6.1.1460>
<code>
12.6.1.1460 <b>F&lt;</b>
</code>
</a>
<BR>
<B>f-less-than</B>   FLOATING
<BR>
<pre>
	( -- flag ) ( F: r1 r2 -- ) 
	or ( r1 r2 -- flag )
</pre>

<P>

flag is true
<P>
if and only if r1 is less than
<P>

<hr>
<A name=12.6.1.1470>
<code>
12.6.1.1460 <b>F&gt;D</b>
</code>
</a>
<BR>
<B>f-to-d</B>        FLOATING
<BR>
<pre>
	( -- d ) ( F: r -- ) 
	or ( r -- d )
</pre>

<P>

d is the double-cell signed-integer equivalent of the integer portion of
r.  The fractional portion of r is discarded.  An ambiguous condition
exists if the integer portion of r cannot be precisely represented as a
double-cell signed integer.

<P>

<hr>
<A name=12.6.1.1472>
<code>
12.6.1.1472 <b>F@</b>
</code>
</a>
<BR>
<B>f-fetch</B>       FLOATING
<BR>
<pre>
	( f-addr -- ) ( F: -- r )  
	or  ( f-addr -- r )
</pre>

<P>

r is
the value stored at f-addr.

<P>

<hr>
<A name=12.6.1.1479>
<code>
12.6.1.1479 <b>FALIGN</b>
</code>
</a>
<BR>
<B>f-align</B>       FLOATING
<BR>
<pre>
	( -- )
</pre>

<P>

If the data-space pointer is not float aligned, reserve enough data
space to make it so.

<P>

<hr>
<A name=12.6.1.1483>
<code>
12.6.1.1483 <b>FALIGNED</b>
</code>
</a>
<BR>
<B>f-aligned</B>     FLOATING
<BR>
<pre>
	( addr -- f-addr )
</pre>
<P>

f-addr is the first float-aligned address greater than or equal to addr.
<P>

<hr>
<A name=12.6.1.1492>
<code>
12.6.1.1492 <b>FCONSTANT</b>
</code>
</a>
<BR>
<B>f-constant</B>    FLOATING
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- ) ( F: r -- ) 
	or ( r <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading space delimiters.  Parse name delimited by a space.  Create
a definition for name with the execution semantics defined below.

<P>

name is
referred to as an <B>f-constant</B>.

<PRE>
        <i>name</i> Execution: ( -- ) ( F: -- r ) 
			       or ( -- r )
</PRE>
<P>

Place r
on the floating-point stack.
<P>

<code>
See:
<a href=dpansa12.htm#A.12.6.1.1492>A.12.6.1.1492 FCONSTANT</a> ,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing.
</code>

<P>

<hr>
<A name=12.6.1.1497>
<code>
12.6.1.1497 <b>FDEPTH</b>
</code>
</a>
<BR>
<B>f-depth</B>       FLOATING
<BR>
<pre>
	( -- +n )
</pre>

<P>

+n is the number of values contained on the default separate
floating-point stack.  If floating-point numbers are kept on the data
stack, +n is the current number of possible floating-point values
contained on the data stack.

<P>

<hr>
<A name=12.6.1.1500>
<code>
12.6.1.1500 <b>FDROP</b>
</code>
</a>
<BR>
<B>f-drop</B>
<BR>
FLOATING
<pre>
	( F: r -- ) 
	or ( r -- )
</pre>

<P>

Remove r
from the floating-point stack.

<P>

<hr>
<A name=12.6.1.1510>
<code>
12.6.1.1510 <b>FDUP</b>
</code>
</a>
<BR>
<B>f-dupe</B>        FLOATING
<BR>
<pre>
	( F: r -- r r ) 
	or ( r -- r r )
</pre>

<P>

Duplicate
r.

<P>

<hr>
<A name=12.6.1.1552>
<code>
12.6.1.1552 <b>FLITERAL</b>
</code>
</a>
<BR>
<B>f-literal</B>     FLOATING
<p>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<PRE>
        Compilation: ( F: r -- ) 
	or ( r -- )
</PRE>
<P>

Append the run-time
semantics given below to the current definition.

<PRE>
        Run-time: ( F: -- r ) 
	or ( -- r )
</PRE>
<P>

Place r
on the floating-point stack.

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.1.1552>A.12.6.1.1552 FLITERAL</a>
</code>
<p>


<hr>
<A name=12.6.1.1555>
<code>
12.6.1.1555 <b>FLOAT+</b>
</code>
</a>
<BR>
<B>FLOAT-plus</B>    FLOATING
<BR>
<pre>
	( f-addr1 -- f-addr2 )
</pre>

<P>

Add the size in address units of a floating-point number to f-addr1,
giving f-addr2.

<P>

<hr>
<A name=12.6.1.1556>
<code>
12.6.1.1556 <b>FLOATS</b>
</code>
</a>
<BR>
FLOATING
<BR>
<pre>
	( n1 -- n2 )
</pre>

<P>

n2 is the
size in address units of n1 floating-point numbers.

<P>

<hr>
<A name=12.6.1.1558>
<code>
12.6.1.1558 <b>FLOOR</b>
</code>
</a>
<BR>
FLOATING
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

Round r1 to an integral value using the <B>round toward negative
infinity</B> rule, giving r2.

<P>

<hr>
<A name=12.6.1.1562>
<code>
12.6.1.1562 <b>FMAX</b>
</code>
</a>
<BR>
<B>f-max</B> FLOATING
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

r3 is
the greater of r1 and r2.

<P>

<hr>
<A name=12.6.1.1565>
<code>
12.6.1.1565 <b>FMIN</b>
</code>
</a>
<BR>
<B>f-min</B> FLOATING
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

r3 is
the lesser of r1 and r2.

<P>

<hr>
<A name=12.6.1.1567>
<code>
12.6.1.1567 <b>FNEGATE</b>
</code>
</a>
<BR>
<B>f-negate</B>      FLOATING
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the negation of r1.

<P>

<hr>
<A name=12.6.1.1600>
<code>
12.6.1.1600 <b>FOVER</b>
</code>
</a>
<BR>
<B>f-over</B>        FLOATING
<BR>
<pre>
	( F: r1 r2 -- r1 r2 r1 ) 
	or ( r1 r2 -- r1 r2 r1 )
</pre>

<P>

Place a
copy of r1 on top of the floating-point stack.

<P>

<hr>
<A name=12.6.1.1610>
<code>
12.6.1.1610 <b>FROT</b>
</code>
</a>
<BR>
<B>f-rote</B>        FLOATING
<BR>
<pre>
	( F: r1 r2 r3 -- r2 r3 r1 ) 
	or ( r1 r2 r3 -- r2 r3 r1 )
</pre>

<P>

Rotate the
top three floating-point stack entries.

<P>

<hr>
<A name=12.6.1.1612>
<code>
12.6.1.1612 <b>FROUND</b>
</code>
</a>
<BR>
<B>f-round</B>       FLOATING
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

Round r1 to
an integral value using the <B>round to nearest</B> rule, giving r2.
<P>

<code>
See:
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations
</code>

<P>

<hr>
<A name=12.6.1.1620>
<code>
12.6.1.1620 <b>FSWAP</b>
</code>
</a>
<BR>
<B>f-swap</B>        FLOATING
<BR>
<pre>
	( F: r1 r2 -- r2 r1 ) 
	or ( r1 r2 -- r2 r1 )
</pre>

<P>

Exchange the
top two floating-point stack items.

<P>

<hr>
<A name=12.6.1.1630>
<code>
12.6.1.1630 <b>FVARIABLE</b>
</code>
</a>
<BR>
<B>f-variable</B>    FLOATING
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading space delimiters.  Parse name delimited by a space.  Create
a definition for name with the execution semantics defined below.
Reserve 1 
<a href=dpans12.htm#12.6.1.1556>FLOATS</a> 
address units of data space at a float-aligned address.

<P>

name is
referred to as an <B>f-variable</B>.

<PRE>
        <i>name</i> Execution: ( -- f-addr )
</PRE>
<P>

f-addr is the address of the data space reserved by FVARIABLE when it
created name.  A program is responsible for initializing the contents of
the reserved space.
<P>

<code>
See:
<a href=dpansa12.htm#A.12.6.1.1630>A.12.6.1.1630 FVARIABLE</a> ,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing.
</code>

<P>

<hr>
<A name=12.6.1.2143>
<code>
12.6.1.2143 <b>REPRESENT</b>
</code>
</a>
<BR>
FLOATING
<BR>
<pre>
	( c-addr u -- n flag1 flag2 )  (F: r -- )  
	or ( r c-addr u -- n flag1 flag2 )
</pre>

<P>

At c-addr, place the character-string external representation of the
significand of the floating-point number r.  Return the decimal-base
exponent as n, the sign as flag1 and <B>valid result</B> as flag2.  The
character string shall consist of the u most significant digits of the
significand represented as a decimal fraction with the implied decimal
point to the left of the first digit, and the first digit zero only if
all digits are zero.  The significand is rounded to u digits following
the <B>round to nearest</B> rule; n is adjusted, if necessary, to
correspond to the rounded magnitude of the significand.  If flag2 is
true then r was in the implementation-defined range of floating-point
numbers.  If flag1 is true then r is negative.

<P>

An ambiguous condition exists
if the value of 
<a href=dpans6.htm#6.1.0750>BASE</a> is not decimal ten.

<P>

When flag2 is false, n and flag1 are implementation defined, as are the
contents of c-addr.  Under these circumstances, the string at c-addr
shall consist of graphic characters.

<P>

<code>
See:
<A href=dpans3.htm#3.2.1.2>3.2.1.2</a> Digit conversion,
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations,
<a href=dpansa12.htm#A.12.6.1.2143>A.12.6.1.2143 REPRESENT</a>
</code>
<P>


<hr>
<a name=12.6.2>
<H3>12.6.2 Floating-Point extension words</H3>
</a>


<hr>
<A name=12.6.2.1203>
<code>
12.6.2.1203 <b>DF!</b>
</code>
</a>
<BR>
<B>d-f-store</B>     FLOATING EXT
<BR>
<pre>
	( df-addr -- ) ( F: r -- ) 
	or ( r df-addr -- )
</pre>

<P>

Store the floating-point number r as a 64-bit IEEE double-precision
number at df-addr.  If the significand of the internal representation of
r has more precision than the IEEE double-precision format, it will be
rounded using the <B>round to nearest</B> rule.  An ambiguous condition
exists if the exponent of r is too large to be accommodated in IEEE
double-precision format.
<p>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses,
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations.
</code>

<P>

<hr>
<A name=12.6.2.1204>
<code>
12.6.2.1204 <b>DF@</b>
</code>
</a>
<BR>
<B>d-f-fetch</B>     FLOATING EXT
<BR>
<pre>
	( df-addr -- ) ( F: -- r ) 
	or ( df-addr -- r )
</pre>

<P>

Fetch the 64-bit IEEE double-precision number stored at df-addr to the
floating-point stack as r in the internal representation.  If the IEEE
double-precision significand has more precision than the internal
representation it will be rounded to the internal representation using
the <B>round to nearest</B> rule.  An ambiguous condition exists if the
exponent of the IEEE double-precision representation is too large to be
accommodated by the internal representation.
<p>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses,
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations.
</code>

<P>

<hr>
<A name=12.6.2.1205>
<code>
12.6.2.1205 <b>DFALIGN</b>
</code>
</a>
<BR>
<B>d-f-align</B>     FLOATING EXT
<BR>
<pre>
	( -- )
</pre>

<P>

If the data-space pointer is not double-float aligned, reserve enough
data space to make it so.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>

<P>

<hr>
<A name=12.6.2.1207>
<code>
12.6.2.1207 <b>DFALIGNED</b>
</code>
</a>
<BR>
<B>d-f-aligned</B>   FLOATING EXT
<BR>
<pre>
	( addr -- df-addr )
</pre>

<P>

df-addr is the first double-float-aligned address greater than or equal
to addr.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>

<P>

<hr>
<A name=12.6.2.1208>
<code>
12.6.2.1208 <b>DFLOAT+</b>
</code>
</a>
<BR>
<B>d-float-plus</B>  FLOATING EXT
<BR>
<pre>
	( df-addr1 -- df-addr2 )
</pre>

<P>

Add the size in address units of a 64-bit IEEE double-precision number
to df-addr1, giving df-addr2.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>

<P>

<hr>
<A name=12.6.2.1209>
<code>
2.6.2.1209 <b>DFLOATS</b>
</code>
</a>
<BR>
<B>d-floats</B>     FLOATING EXT
<BR>
<pre>
	( n1 -- n2 )
</pre>

<P>

n2 is the size in address units of n1 64-bit IEEE double-precision
numbers.

<P>

<hr>
<A name=12.6.2.1415>
<code>
12.6.2.1415 <b>F**</b>
</code>
</a>
<BR>
<B>f-star-star</B>   FLOATING EXT
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

Raise r1 to
the power r2, giving the product r3.

<P>

<hr>
<A name=12.6.2.1427>
<code>
12.6.2.1427 <b>F.</b>
</code>
</a>
<BR>
<B>f-dot</B> FLOATING EXT
<BR>
<pre>
	( -- ) ( F: r -- ) 
	or ( r -- )
</pre>

<P>

Display, with a trailing space, the top number on the floating-point
stack using fixed-point notation:

<PRE>
	[-] &lt;digits&gt;.&lt;digits0&gt;
</PRE>
<P>

An ambiguous condition exists if the value of 
<a href=dpans6.htm#6.1.0750>BASE</a> is not (decimal) ten
or if the character string representation exceeds the size of the
pictured numeric output string buffer.
<P>

<code>
See:    
<A href=dpans12.htm#12.6.1.0558>12.6.1.0558 &gt;FLOAT</a> ,
<a href=dpansa12.htm#A.12.6.1.1427>A.12.6.1.1427 F.</a>
</code>

<P>

<hr>
<A name=12.6.2.1474>
<code>
12.6.2.1474 <b>FABS</b>
</code>
</a>
<BR>
<B>f-abs</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the absolute value of r1.

<P>

<hr>
<A name=12.6.2.1476>
<code>
12.6.2.1476 <b>FACOS</b>
</code>
</a>
<BR>
<B>f-a-cos</B>       FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the principal radian angle whose cosine is r1.  An ambiguous
condition exists if |r1| is greater than one.

<P>

<hr>
<A name=12.6.2.1477>
<code>
12.6.2.1477 <b>FACOSH</b>
</code>
</a>
<BR>
<B>f-a-cosh</B>      FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the floating-point value whose hyperbolic cosine is r1.  An
ambiguous condition exists if r1 is less than one.

<P>

<hr>
<A name=12.6.2.1484>
<code>
12.6.2.1484 <b>FALOG</b>
</code>
</a>
<BR>
<B>f-a-log</B>       FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

Raise ten
to the power r1, giving r2.

<P>

<hr>
<A name=12.6.2.1486>
<code>
12.6.2.1486 <b>FASIN</b>
</code>
</a>
<BR>
<B>f-a-sine</B>      FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the principal radian angle whose sine is r1.  An ambiguous
condition exists if |r1| is greater than one.

<P>

<hr>
<A name=12.6.2.1487>
<code>
12.6.2.1487 <b>FASINH</b>
</code>
</a>
<BR>
<B>f-a-cinch</B>     FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the floating-point value whose hyperbolic sine is r1.  An
ambiguous condition exists if r1 is less than zero.

<P>

<hr>
<A name=12.6.2.1488>
<code>
12.6.2.1488 <b>FATAN</b>
</code>
</a>
<BR>
<B>f-a-tan</B>       FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the principal radian angle whose tangent is r1.

<P>

<hr>
<A name=12.6.2.1489>
<code>
12.6.2.1489 <b>FATAN2</b>
</code>
</a>
<BR>
<B>f-a-tan-two</B>   FLOATING EXT
<BR>
<pre>
	( F: r1 r2 -- r3 ) 
	or ( r1 r2 -- r3 )
</pre>

<P>

r3 is the radian angle whose tangent is r1/r2.  An ambiguous condition
exists if r1 and r2 are zero.

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.2.1489>A.12.6.2.1489 FATAN2</a>
</code>
<p>


<hr>
<A name=12.6.2.1491>
<code>
12.6.2.1491 <b>FATANH</b>
</code>
</a>
<BR>
<B>f-a-tan-h</B>     FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the floating-point value whose hyperbolic tangent is r1.  An
ambiguous condition exists if r1 is outside the range of -1E0 to 1E0.

<P>

<hr>
<A name=12.6.2.1493>
<code>
12.6.2.1493 <b>FCOS</b>
</code>
</a>
<BR>
<B>f-cos</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the
cosine of the radian angle r1.

<P>

<hr>
<A name=12.6.2.1494>
<code>
12.6.2.1494 <b>FCOSH</b>
</code>
</a>
<BR>
<B>f-cosh</B>        FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the hyperbolic cosine of r1.

<P>

<hr>
<A name=12.6.2.1513>
<code>
12.6.2.1513 <b>FE.</b>
</code>
</a>
<BR>
<B>f-e-dot</B>       FLOATING EXT
<BR>
<pre>
	( -- ) ( F: r -- ) 
	or ( r -- )
</pre>

<P>

Display, with a trailing space, the top number on the floating-point
stack using engineering notation, where the significand is greater than
or equal to 1.0 and less than 1000.0 and the decimal exponent is a
multiple of three.

<P>

An ambiguous condition exists if the value of 
<a href=dpans6.htm#6.1.0750>BASE</a> is not (decimal) ten
or if the character string representation exceeds the size of the
pictured numeric output string buffer.

<P>

<code>
See:
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations,
<A href=dpans12.htm#12.6.1.2143>12.6.1.2143 REPRESENT</a>
</code>

<P>

<hr>
<A name=12.6.2.1515>
<code>
12.6.2.1515 <b>FEXP</b>
</code>
</a>
<BR>
<B>f-e-x-p</B>       FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

Raise e to the power r1, giving r2.

<P>

<hr>
<A name=12.6.2.1516>
<code>
12.6.2.1516 <b>FEXPM1</b>
</code>
</a>
<BR>
<B>f-e-x-p-m-one</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

Raise e
to the power r1 and subtract one, giving r2.

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.2.1516>A.12.6.2.1516 FEXPM1</a>
</code>
<p>


<hr>
<A name=12.6.2.1553>
<code>
12.6.2.1553 <b>FLN</b>
</code>
</a>
<BR>
<B>f-l-n</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the natural logarithm of r1.  An ambiguous condition exists if r1
is less than or equal to zero.

<P>

<hr>
<A name=12.6.2.1554>
<code>
12.6.2.1554 <b>FLNP1</b>
</code>
</a>
<BR>
<B>f-l-n-p-one</B>   FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the natural logarithm of the quantity r1 plus one.  An ambiguous
condition exists if r1 is less than or equal to negative one.

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.2.1554>A.12.6.2.1554 FLNP1</a>
</code>
<p>


<hr>
<A name=12.6.2.1557>
<code>
12.6.2.1557 <b>FLOG</b>
</code>
</a>
<BR>
<B>f-log</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the base-ten logarithm of r1.  An ambiguous condition exists if r1
is less than or equal to zero.

<P>

<hr>
<A name=12.6.2.1613>
<code>
12.6.2.1613 <b>FS.</b>
</code>
</a>
<BR>
<B>f-s-dot</B>       FLOATING EXT
<BR>
<pre>
	( -- ) ( F: r -- ) 
	or ( r -- )
</pre>

<P>

Display, with a trailing space, the top number on the floating-point
stack in scientific notation:

<PRE>
	&lt;significand&gt;&lt;exponent&gt;
</PRE>
<P>

where:
<P>


<PRE>
	&lt;significand>  :=  [-]&lt;digit&gt;.&lt;digits0&gt;
	&lt;exponent>     :=  E[-]&lt;digits&gt;
</PRE>
<P>

An ambiguous condition exists if the value of 
<a href=dpans6.htm#6.1.0750>BASE</a> is not (decimal) ten
or if the character string representation exceeds the size of the
pictured numeric output string buffer.

<P>

<code>
See:
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations,
<A href=dpans12.htm#12.6.1.2143>12.6.1.2143 REPRESENT</a>
</code>

<P>

<hr>
<A name=12.6.2.1614>
<code>
12.6.2.1614 <b>FSIN</b>
</code>
</a>
<BR>
<B>f-sine</B>        FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the sine of the radian angle r1.

<P>

<hr>
<A name=12.6.2.1616>
<code>
12.6.2.1616 <b>FSINCOS</b>
</code>
</a>
<BR>
<B>f-sine-cos</B>    FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 r3 ) 
	or ( r1 -- r2 r3 )
</pre>

<P>

r2 is the sine of the radian angle r1.  r3 is the cosine of the radian
angle r1.

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.2.1489>A.12.6.2.1489 FATAN2</a>
</code>
<p>


<hr>
<A name=12.6.2.1617>
<code>
12.6.2.1617 <b>FSINH</b>
</code>
</a>
<BR>
<B>f-cinch</B>       FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the hyperbolic sine of r1.

<P>

<hr>
<A name=12.6.2.1618>
<code>
12.6.2.1618 <b>FSQRT</b>
</code>
</a>
<BR>
<B>f-square-root</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the square root of r1.  An ambiguous condition exists if r1 is
less than zero.

<P>

<hr>
<A name=12.6.2.1625>
<code>
12.6.2.1625 <b>FTAN</b>
</code>
</a>
<BR>
<B>f-tan</B> FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is the tangent of the radian angle r1.  An ambiguous condition exists
if cos(r1) is zero.

<P>

<hr>
<A name=12.6.2.1626>
<code>
12.6.2.1626 <b>FTANH</b>
</code>
</a>
<BR>
<B>f-tan-h</B>       FLOATING EXT
<BR>
<pre>
	( F: r1 -- r2 ) 
	or ( r1 -- r2 )
</pre>

<P>

r2 is
the hyperbolic tangent of r1.

<P>

<hr>
<A name=12.6.2.1640>
<code>
12.6.2.1640 <b>F~</b>
</code>
</a>
<BR>
<B>f-proximate</B>   FLOATING EXT
<BR>(
<pre>
	( -- flag ) ( F: r1 r2 r3 -- ) 
	or ( r1 r2 r3 -- flag )
</pre>

<P>

If r3 is positive, flag is true if the absolute value of (r1 minus r2)
is less than r3.

<P>

If r3 is zero, flag is true if the implementation-dependent encoding of
r1 and r2 are exactly identical (positive and negative zero are unequal
if they have distinct encodings).

<P>

If r3 is negative, flag is true if the absolute value of (r1 minus r2)
is less than the absolute value of r3 times the sum of the absolute
values of r1 and r2.

<p>
<code>
See:
<a href=dpansa12.htm#A.12.6.2.1640>A.12.6.2.1640 F~</a>
</code>
<p>


<hr>
<A name=12.6.2.2035>
<code>
12.6.2.2035 <b>PRECISION</b>
</code>
</a>
<BR>
FLOATING EXT
<BR>
<pre>
	( -- u )
</pre>

<P>

Return the number of significant digits currently used by 
<a href=dpans12.htm#12.6.2.1427>F.</a>, 
<a href=dpans12.htm#12.6.2.1513>FE.</a>, or
<a href=dpans12.htm#12.6.2.1613>FS.</a> as u.

<P>

<hr>
<A name=12.6.2.2200>
<code>
12.6.2.2200 <b>SET-PRECISION</b>
</code>
</a>
<BR>
FLOATING EXT
<BR>
<pre>
	( u -- )
</pre>

<P>

Set the number of significant digits currently used by 
<a href=dpans12.htm#12.6.2.1427>F.</a>, 
<a href=dpans12.htm#12.6.2.1513>FE.</a>, or
<a href=dpans12.htm#12.6.2.1613>FS.</a> to u.

<P>

<hr>
<A name=12.6.2.2202>
<code>
12.6.2.2202 <b>SF!</b>
</code>
</a>
<BR>
<B>s-f-store</B>     FLOATING EXT
<BR>
<pre>
	( sf-addr -- ) ( F: r -- ) 
	or ( r sf-addr -- )
</pre>

<P>

Store the floating-point number r as a 32-bit IEEE single-precision
number at sf-addr.  If the significand of the internal representation of
r has more precision than the IEEE single-precision format, it will be
rounded using the <B>round to nearest</B> rule.  An ambiguous condition
exists if the exponent of r is too large to be accommodated by the IEEE
single-precision format.
<p>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses,
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations.
</code>

<P>

<hr>
<A name=12.6.2.2203>
<code>
12.6.2.2203 <b>SF@</b>
</code>
</a>
<BR>
<B>s-f-fetch</B>     FLOATING EXT
<BR>
<pre>
	( sf-addr -- ) ( F: -- r ) 
	or ( sf-addr -- r )
</pre>

<P>

Fetch the 32-bit IEEE single-precision number stored at sf-addr to the
floating-point stack as r in the internal representation.  If the IEEE
single-precision significand has more precision than the internal
representation, it will be rounded to the internal representation using
the <B>round to nearest</B> rule.  An ambiguous condition exists if the
exponent of the IEEE single-precision representation is too large to be
accommodated by the internal representation.
<p>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses,
<A href=dpans12.htm#12.3.2>12.3.2</a> Floating-point operations.
</code>

<P>

<hr>
<A name=12.6.2.2204>
<code>
12.6.2.2204 <b>SFALIGN</b>
</code>
</a>
<BR>
<B>s-f-align</B>     FLOATING EXT
<BR>
<pre>
	( -- )
</pre>

<P>

If the data-space pointer is not single-float aligned, reserve enough
data space to make it so.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>

<P>

<hr>
<A name=12.6.2.2206>
<code>
12.6.2.2206 <b>SFALIGNED</b>
</code>
</a>
<BR>
<B>s-f-aligned</B>   FLOATING EXT
<BR>
<pre>
	( addr -- sf-addr )
</pre>

<P>

sf-addr is the first single-float-aligned address greater than or equal
to addr.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>

<P>

<hr>
<A name=12.6.2.2207>
<code>
12.6.2.2207 <b>SFLOAT+</b>
</code>
</a>
<BR>
<B>s-float-plus</B>  FLOATING EXT
<BR>
<pre>
	( sf-addr1 -- sf-addr2 )
</pre>

<P>

Add the size in address units of a 32-bit IEEE single-precision number
to sf-addr1, giving sf-addr2.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>

<P>

<hr>
<A name=12.6.2.2208>
<code>
12.6.2.2208 <b>SFLOATS</b>
</code>
</a>
<BR>
<B>s-floats</B>      FLOATING EXT
<BR>
<pre>
	( n1 -- n2 )
</pre>

<P>

n2 is the size in address units of n1 32-bit IEEE single-precision
numbers.
<P>

<code>
See:
<A href=dpans12.htm#12.3.1.1>12.3.1.1</a> Addresses
</code>


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans13.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans13.htm/    851247240   500   0     100644  14428     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans12.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans14.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=13.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>13. The optional Locals word set</H1>


<hr>
<A name=13.1>
<H2>13.1 Introduction</H2>
</a>

<p>
<code>
See:
<A href=dpansa13.htm>Annex A.13</a> The Locals Word Set
</code>
<P>

<hr>
<A name=13.2>
<H2>13.2 Additional terms and notation</H2>
</a>

None.
<P>

<hr>
<A name=13.3>
<H2>13.3 Additional usage requirements</H2>
</a>

<p>
<code>
See:  
<A href=dpansa13.htm#A.13.3>A.13.3</a> Additional usage requirements
</code>
<P>

<hr>
<A name=13.3.1>
<H3>13.3.1 Locals</H3>
</a>

A local is a data object whose execution semantics shall return its
value, whose scope shall be limited to the definition in which it is
declared, and whose use in a definition shall not preclude reentrancy or
recursion.

<P>

<hr>
<A name=13.3.2>
<H3>13.3.2 Environmental queries</H3>
</a>

Append table 13.1 to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>

<P>

Table 13.1 - Environmental query strings
<P>



<PRE>
String          Value data type  Constant?  Meaning
------          ---------------  ---------  -------
#LOCALS         n                yes        maximum number of local variables in a definition
LOCALS          flag             no         locals word set present
LOCALS-EXT      flag             no         locals extensions word set present
</PRE>


<P>

<hr>
<A name=13.3.3>
<H3>13.3.3 Processing locals</H3>
</a>

To support the locals word set, a system shall provide a mechanism to
receive the messages defined by 
<a href=dpans13.htm#13.6.1.0086>(LOCAL)</a> 
and respond as described here.

<P>

During the compilation of a definition after : 
(<a href=dpans6.htm#6.1.0450>colon</a>), 
<a href=dpans6.htm#6.2.0455>:NONAME</a>, or
<a href=dpans6.htm#6.1.1250>DOES></a>, 
a program may begin sending local identifier messages to the
system.  The process shall begin when the first message is sent.  The
process shall end when the <B>last local</B> message is sent.  The
system shall keep track of the names, order, and number of identifiers
contained in the complete sequence.

<P>

<hr>
<A name=13.3.3.1>
<H4>13.3.3.1 Compilation semantics</H4>
</a>

The system, upon receipt of a sequence of local-identifier messages,
shall take the following actions at compile time:

<P>

a) Create temporary dictionary entries for each of the identifiers
passed to 
<a href=dpans13.htm#13.6.1.0086>(LOCAL)</a>, 
such that each identifier will behave as a local.
These temporary dictionary entries shall vanish at the end of the
definition, denoted by ; 
(<a href=dpans6.htm#6.1.0460>semicolon</a>), 
<a href=dpans15.htm#15.6.2.0470>;CODE</a>, or 
<a href=dpans6.htm#6.1.1250>DOES></a>.  The system need
not maintain these identifiers in the same way it does other dictionary
entries as long as they can be found by normal dictionary searching
processes.  Furthermore, if the Search-Order word set is present, local
identifiers shall always be searched before any of the word lists in any
definable search order, and none of the Search-Order words shall change
the locals' privileged position in the search order.  Local identifiers
may reside in mass storage.

<P>

b) For each identifier passed to (LOCAL), the system shall generate an
appropriate code sequence that does the following at execution time:

<P>

<OL>
<LI>Allocate a storage resource adequate to contain the value of a local.
The storage shall be allocated in a way that does not preclude
re-entrancy or recursion in the definition using the local.
<LI>Initialize the value using the top item on the data stack. If more
than one local is declared, the top item on the stack shall be moved
into the first local identified, the next item shall be moved into the
second, and so on.
</ol>

The storage resource may be the return stack or may be implemented in
other ways, such as in registers. The storage resource shall not be
the data stack. Use of locals shall not restrict use of the data
stack before or after the point of declaration.
<p>

c) Arrange that any of the legitimate methods of terminating execution
of a definition, specifically ; (semicolon), ;CODE, DOES> or 
<a href=dpans6.htm#6.1.1380>EXIT</a>, will
release the storage resource allocated for the locals, if any, declared
in that definition.  
<a href=dpans6.htm#6.1.0670>ABORT</a> 
shall release all local storage resources,
and 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> / 
<a href=dpans9.htm#9.6.1.2275>THROW</a> 
(if implemented) shall release such resources for all
definitions whose execution is being terminated.

<P>

d) Separate sets of locals may be declared in defining words before
DOES> for use by the defining word, and after DOES> for use by the word
defined.

<P>

A system implementing the Locals word set shall support the declaration
of at least eight locals in a definition.

<P>

<hr>
<A name=13.3.3.2>
<H4>13.3.3.2 Syntax restrictions</H4>
</a>

Immediate words in a program may use 
<a href=dpans13.htm#13.6.1.0086>(LOCAL)</a> to implement syntaxes for
local declarations with the following restrictions:

<P>

a) A program shall not compile any executable code into the current
definition between the time (LOCAL) is executed to identify the first
local for that definition and the time of sending the single required
<B>last local</B> message;

<P>

b) The position in program source at which the sequence of (LOCAL)
messages is sent, referred to here as the point at which locals are
declared, shall not lie within the scope of any control structure;

<P>

c) Locals shall not be declared until values previously placed on the
return stack within the definition have been removed;

<P>

d) After a definition's locals have been declared, a program may place
data on the return stack.  However, if this is done, locals shall not be
accessed until those values have been removed from the return stack;

<P>

e) Words that return execution tokens, such as ' 
(<a href=dpans6.htm#6.1.0070>tick</a>), 
<a href=dpans6.htm#6.1.2510>[']</a>, or 
<a href=dpans6.htm#6.1.1550>FIND</a>,
shall not be used with local names;

<P>

f) A program that declares more than eight locals in a single definition
has an environmental dependency;

<P>

g) Locals may be accessed or updated within control structures,
including do-loops;

<P>

h) Local names shall not be referenced by 
<a href=dpans6.htm#6.1.2033>POSTPONE</a> and 
<a href=dpans6.htm#6.2.2530>[COMPILE]</a>.
<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter
</code>

<P>

<hr>
<A name=13.4>
<H2>13.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=13.4.1>
<H3>13.4.1 System documentation</H3>
</a>


<hr>
<A name=13.4.1.1>
<H4>13.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>maximum number of locals in a definition 
(<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals,
<a href=dpans13.htm#13.6.2.1795>13.6.2.1795</a> LOCALS|).
</UL>

<P>

<hr>
<A name=13.4.1.2>
<H4>13.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI>executing a named local while in interpretation state 
(<a href=dpans13.htm#13.6.1.0086>13.6.1.0086</a>
(LOCAL));
<LI>name not defined by 
<a href=dpans6.htm#6.2.2405>VALUE</a> or 
LOCAL 
(<a href=dpans13.htm#13.6.1.2295>13.6.1.2295</a> TO).
</ul>

<hr>
<A name=13.4.1.3>
<h4>13.4.1.3 Other system documentation</h4>
</a>
<ul>
<LI>no additional requirements.
</UL>
<P>

<hr>
<A name=13.4.2>
<H3>13.4.2 Program documentation</H3>
</a>


<hr>
<A name=13.4.2.1>
<H4>13.4.2.1 Environmental dependencies</H4>
</a>

<UL>
<LI>declaring more than eight locals in a single definition 
(<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals).
</UL>

<P>

<hr>
<A name=13.4.2.2>
<H4>13.4.2.2 Other program documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>

<P>

<hr>
<A name=13.5>
<H2>13.5 Compliance and labeling</H2>
</a>


<hr>
<A name=13.5.1>
<H3>13.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Locals word set</B> shall be appended to the
label of any Standard System that provides all of the Locals word set.

<P>

The phrase <B>Providing name(s) from the Locals Extensions word set</B>
shall be appended to the label of any Standard System that provides
portions of the Locals Extensions word set.

<P>

The phrase <B>Providing the Locals Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
Locals and Locals Extensions word sets.

<P>

<hr>
<A name=13.5.2>
<H3>13.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Locals word set</B> shall be appended to the
label of Standard Programs that require the system to provide the Locals
word set.

<P>

The phrase <B>Requiring name(s) from the Locals Extensions word set</B>
shall be appended to the label of Standard Programs that require the
system to provide portions of the Locals Extensions word set.

<P>

The phrase <B>Requiring the Locals Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the Locals and Locals Extensions word sets.

<P>

<hr>
<A name=13.6>
<H2>13.6 Glossary</H2>
</a>


<hr>
<A name=13.6.1>
<H3>13.6.1 Locals words</H3>
</a>


<hr>
<A name=13.6.1.0086>
<code>
13.6.1.0086 <b>(LOCAL)</b>
</code>
</a>
<BR>
<B>paren-local-paren</B>     LOCAL
<p>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( c-addr u -- )
</pre>
<P>

When executed during compilation, (LOCAL) passes a message to the system
that has one of two meanings.  If u is non-zero, the message identifies
a new local whose definition name is given by the string of characters
identified by c-addr u.  If u is zero, the message is <B>last local</B>
and c-addr has no significance.

<P>

The result of executing (LOCAL) during compilation of a definition is to
create a set of named local identifiers, each of which is a definition
name, that only have execution semantics within the scope of that
definition's source.

<PRE>
        <i>local</i> Execution: ( -- x )
</PRE>
<P>

Push the local's value, x, onto the stack.  The local's value is
initialized as described in 
<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals and may be changed
by preceding the local's name with 
<a href=dpans13.htm#13.6.1.2295>TO</a>.  An ambiguous condition exists
when local is executed while in interpretation state.
<p>

<b>Note:</b> This word does not have special compilation semantics in
the
usual sense because it provides access to a system capability for use
by other user-defined words that do have them.  However, the locals
facility as a whole and the sequence of messages passed defines
specific usage rules with semantic implications that are described in
detail in section 
<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals.

<P>

<b>Note:</b> This word is not intended for direct use in a definition to
declare that definition's locals.  It is instead used by system or
user compiling words.  These compiling words in turn define their own
syntax, and may be used directly in definitions to declare locals.  In
this context, the syntax for (LOCAL) is defined in terms of a sequence
of compile-time messages and is described in detail in section 
<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals.

<P>

<b>Note:</b> The Locals word set modifies the syntax and semantics of
<a href=dpans6.htm#6.2.2295>6.2.2295</a> TO 
as defined in the Core Extensions word set.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter
</code>

<P>

<hr>
<A name=13.6.1.2295>
<code>
13.6.1.2295 <b>TO</b>
</code>
</a>
<BR>
LOCAL
<BR>
<P>

Extend the semantics of 
<a href=dpans6.htm#6.2.2295>6.2.2295</a> TO to be:
<P>

	
<PRE>
        Interpretation: ( x <B>"&lt;spaces&gt;name"</B> -- )
</PRE>
<P>

Skip leading spaces and parse name delimited by a space.  Store x in
name.  An ambiguous condition exists if name was not defined by 
<a href=dpans6.htm#6.2.2405>VALUE</a>.


<PRE>
        Compilation: ( <B>"&lt;spaces&gt;name"</B> -- )
</PRE>
<P>

Skip leading spaces and parse name delimited by a space.  Append the
run-time semantics given below to the current definition.  An ambiguous
condition exists if name was not defined by either VALUE or 
<a href=dpans13.htm#13.6.1.0086>(LOCAL)</a>.


<PRE>
        Run-time:       ( x -- )
</PRE>
<P>

Store x in name.

<P>

<b>Note:</b> An ambiguous condition exists if either 
<a href=dpans6.htm#6.1.2033>POSTPONE</a> or
<a href=dpans6.htm#6.2.2530>[COMPILE]</a>
is applied to TO.


<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa13.htm#A.13.6.1.2295>A.13.6.1.2295 TO</a>
</code>

<P>

<hr>
<A name=13.6.2>
<H3>13.6.2 Locals extension words</H3>
</a>


<hr>
<A name=13.6.2.1795>
<code>
13.6.2.1795 <b>LOCALS|</b>
</code>
</a>
<BR>
<B>locals-bar</B>    LOCAL EXT
<p>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"&lt;spaces&gt;name1"</B> <B>"&lt;spaces&gt;name2"</B> ... <B>"&lt;spaces&gt;namen"</B> <B>|</B> -- )
</pre>
<P>

Create up to eight local identifiers by repeatedly skipping leading
spaces, parsing name, and executing 
<a href=dpans13.htm#13.6.1.0086>13.6.1.0086</a> (LOCAL).  The list of
locals to be defined is terminated by |.  Append the run-time semantics
given below to the current definition.

<PRE>
        Run-time:       ( xn ... x2 x1 -- )
</PRE>
<P>

Initialize up to eight local identifiers as described in 
<a href=dpans13.htm#13.6.1.0086>13.6.1.0086</a> (LOCAL), 
each of which takes as its initial value the top stack item,
removing it from the stack.  Identifier name1 is initialized with x1,
identifier name2 with x2, etc.  When invoked, each local will return its
value.  The value of a local may be changed using 
<a href=dpans13.htm#13.6.1.2295>13.6.1.2295</a> TO.

<p>
<code>
See:  
<A href=dpansa13.htm#A.13.6.2.1795>A.13.6.2.1795 LOCALS|</a>
</code>
<P>


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans14.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans14.htm/    851247300   500   0     100644  7543      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans13.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans15.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=14.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>14. The optional Memory-Allocation word set</H1>


<hr>
<A name=14.1>
<H2>14.1 Introduction</H2>
</a>

<p>
<code>
See:
<a href=dpansa14.htm>A.14</a> The optional Memory-Allocation word set
</code>
<p>

<hr>
<A name=14.2>
<H2>14.2 Additional terms and notation</H2>
</a>

None.
<P>

<hr>
<A name=14.3>
<H2>14.3 Additional usage requirements</H2>
</a>


<hr>
<A name=14.3.1>
<H3>14.3.1 I/O Results data type</H3>
</a>

I/O results are single-cell numbers indicating the result of I/O
operations.  A value of zero indicates that the I/O operation completed
successfully; other values and their meanings are
implementation-defined.

<P>

Append table 14.1 to 
<a href=dpans3.htm#table.3.1>table 3.1</a>.
<P>

Table 14.1 - Data types

<PRE>
Symbol  Data type       Size on stack
------  ---------       -------------
ior     I/O results     1 cell
</PRE>


<P>

<hr>
<A name=14.3.2>
<H3>14.3.2 Environmental queries</H3>
</a>

Append table 14.2 to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 14.2 - Environmental query strings

<PRE>
String             Value data type  Constant?  Meaning
------             ---------------  ---------  -------
MEMORY-ALLOC       flag             no         memory-allocation word set present
MEMORY-ALLOC-EXT   flag             no         memory-allocation extensions word set present

</PRE>

<P>

<hr>
<A name=14.3.3>
<H3>14.3.3 Allocated regions</H3>
</a>

A program may address memory in data space regions made available by
<a href=dpans14.htm#14.6.1.0707>ALLOCATE</a> or 
<a href=dpans14.htm#14.6.1.2145>RESIZE</a> and not yet released by 
<a href=dpans14.htm#14.6.1.1605>FREE</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space
</code>
<P>


<hr>
<A name=14.4>
<H2>14.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=14.4.1>
<H3>14.4.1 System documentation</H3>
</a>


<hr>
<A name=14.4.1.1>
<H4>14.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>values and meaning of ior 
(<a href=dpans14.htm#14.3.1>14.3.1</a> I/O Results data type,
<a href=dpans14.htm#14.6.1.0707>14.6.1.0707</a> ALLOCATE, 
<a href=dpans14.htm#14.6.1.1605>14.6.1.1605</a> FREE, 
<a href=dpans14.htm#14.6.1.2145>14.6.1.2145</a> RESIZE).
</UL>

<P>

<hr>
<A name=14.4.1.2>
<H4>14.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI>no additional requirements.
</ul>

<hr>
<A name=14.4.1.3>
<h4>14.4.1.3 Other system documentation</h4>
</a>
<ul>
<LI>no additional requirements.
</ul>

<hr>
<A name=14.4.2>
<h3>14.4.2 Program documentation</h3>
</a>
<ul>
<LI>no additional requirements.
</ul>

<hr>
<A name=14.5>
<h2>14.5 Compliance and labeling</h2>
</a>


<P>

<hr>
<A name=14.5.1>
<H3>14.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Memory-Allocation word set</B> shall be
appended to the label of any Standard System that provides all of the
Memory-Allocation word set.

<P>

The phrase <B>Providing name(s) from the Memory-Allocation Extensions
word set</B> shall be appended to the label of any Standard System that
provides portions of the Memory-Allocation Extensions word set.

<P>

The phrase <B>Providing the Memory-Allocation Extensions word set</B>
shall be appended to the label of any Standard System that provides all
of the Memory-Allocation and Memory-Allocation Extensions word sets.

<P>

<hr>
<A name=14.5.2>
<H3>14.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Memory-Allocation word set</B> shall be
appended to the label of Standard Programs that require the system to
provide the Memory-Allocation word set.

<P>

The phrase <B>Requiring name(s) from the Memory-Allocation Extensions
word set</B> shall be appended to the label of Standard Programs that
require the system to provide portions of the Memory-Allocation
Extensions word set.

<P>

The phrase <B>Requiring the Memory-Allocation Extensions word set</B>
shall be appended to the label of Standard Programs that require the
system to provide all of the Memory-Allocation and Memory-Allocation
Extensions word sets.

<P>

<hr>
<A name=14.6>
<H2>14.6 Glossary</H2>
</a>

<hr>
<A name=14.6.1>
<H3>14.6.1 Memory-Allocation words</H3>
</a>

<hr>
<A name=14.6.1.0707>
<code>
14.6.1.0707 <b>ALLOCATE</b>
</code>
</a>
<BR>
MEMORY
<BR>
<pre>
	( u -- a-addr ior )
</pre>
<P>

Allocate u address units of contiguous data space.  The data-space
pointer is unaffected by this operation.  The initial content of the
allocated space is undefined.

<P>

If the allocation succeeds, a-addr is the aligned starting address of
the allocated space and ior is zero.

<P>

If the operation fails, a-addr does not represent a valid address and
ior is the implementation-defined I/O result code.

<p>

<code>
See:    
<A href=dpans6.htm#6.1.1650>6.1.1650 HERE</a> ,
<A href=dpans14.htm#14.6.1.1605>14.6.1.1605 FREE</a> ,
<A href=dpans14.htm#14.6.1.2145>14.6.1.2145 RESIZE</a>
</code>

<P>

<hr>
<A name=14.6.1.1605>
<code>
14.6.1.1605 <b>FREE</b>
</code>
</a>
<BR>
MEMORY
<BR>
<pre>
	( a-addr -- ior )
</pre>
<P>

Return the contiguous region of data space indicated by a-addr to the
system for later allocation.  a-addr shall indicate a region of data
space that was previously obtained by 
<a href=dpans14.htm#14.6.1.0707>ALLOCATE</a> or 
<a href=dpans14.htm#14.6.1.2145>RESIZE</a>.  The
data-space pointer is unaffected by this operation.
<P>

If the operation succeeds, ior is zero.  If the operation fails, ior is
the implementation-defined I/O result code.
<P>

<code>
See:    
<A href=dpans6.htm#6.1.1650>6.1.1650 HERE</a>
</code>

<P>

<hr>
<A name=14.6.1.2145>
<code>
14.6.1.2145 <b>RESIZE</b>
</code>
</a>
<BR>
MEMORY
<BR>
<pre>
	( a-addr1 u -- a-addr2 ior )
</pre>
<P>

Change the allocation of the contiguous data space starting at the
address a-addr1, previously allocated by 
<a href=dpans14.htm#14.6.1.0707>ALLOCATE</a> or RESIZE, to u
address units.  u may be either larger or smaller than the current size
of the region.  The data-space pointer is unaffected by this operation.

<P>

If the operation succeeds, a-addr2 is the aligned starting address of u
address units of allocated memory and ior is zero.  a-addr2 may be, but
need not be, the same as a-addr1.  If they are not the same, the values
contained in the region at a-addr1 are copied to a-addr2, up to the
minimum size of either of the two regions.  If they are the same, the
values contained in the region are preserved to the minimum of u or the
original size.  If a-addr2 is not the same as a-addr1, the region of
memory at a-addr1 is returned to the system according to the operation
of 
<a href=dpans14.htm#14.6.1.1605>FREE</a>.

<P>

If the operation fails, a-addr2 equals a-addr1, the region of memory at
a-addr1 is unaffected, and ior is the implementation-defined I/O result
code.
<P>

<code>
See:    
<A href=dpans6.htm#6.1.1650>6.1.1650 HERE</a>
</code>

<P>

<hr>
<A name=14.6.2>
<h3>14.6.2   Memory-Allocation extension words</h3>
</a>
<p>

None
<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans15.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpans15.htm/    851247300   500   0     100644  18378     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans14.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans16.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=15.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>15. The optional Programming-Tools word set</H1>

<p>
<code>
See:
<a href=dpansa15.htm>15.</a> The optional Programming-Tools word set
</code>
<p>

<hr>
<A name=15.1>
<H2>15.1 Introduction</H2>
</a>

This optional word set contains words most often used during the development
of applications.
<P>

<hr>
<A name=15.2>
<H2>15.2 Additional terms and notation</H2>
</a>

None.
<P>

<hr>
<A name=15.3>
<H2>15.3 Additional usage requirements</H2>
</a>


<hr>
<A name=15.3.1>
<H3>15.3.1 Environmental queries</H3>
</a>

Append table 15.1 to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 15.1 - Environmental query strings
<P>


<PRE>
String      Value data type   Constant?  Meaning
------      ---------------   ---------  -------
TOOLS       flag              no         programming-tools word set present
TOOLS-EXT   flag              no         programming-tools extensions word set present
</PRE>


<P>

<hr>
<A name=15.3.2>
<H3>15.3.2 The Forth dictionary</H3>
</a>

A program using the words 
<a href=dpans15.htm#15.6.2.0930>CODE</a> or 
<a href=dpans15.htm#15.6.2.0470>;CODE</a> 
associated with assembler code has an
environmental dependency on that particular instruction set and assembler
notation.

<P>

Programs using the words 
<a href=dpans15.htm#15.6.2.1300>EDITOR</a> or 
<a href=dpans15.htm#15.6.2.0740>ASSEMBLER</a> 
require the 
<a href=dpans16.htm>Search Order word set</a>
or an equivalent implementation-defined capability.

<P>

<code>
See:
<A href=dpans3.htm#3.3>3.3</a> The Forth dictionary
</code>

<P>

<hr>
<A name=15.4>
<H2>15.4 Additional documentation requirements</H2>
</a>

<hr>
<A name=15.4.1>
<H3>15.4.1 System documentation</H3>
</a>

<hr>
<A name=15.4.1.1>
<H4>15.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>ending sequence for input following 
<a href=dpans15.htm#15.6.2.0470>15.6.2.0470</a> ;CODE and 
<a href=dpans15.htm#15.6.2.0930>15.6.2.0930</a> CODE;
<LI>manner of processing input following 
<a href=dpans15.htm#15.6.2.0470>15.6.2.0470</a> ;CODE and 
<a href=dpans15.htm#15.6.2.0930>15.6.2.0930</a> CODE;
<LI>search-order capability for 
<a href=dpans15.htm#15.6.2.1300>15.6.2.1300</a> EDITOR and 
<a href=dpans15.htm#15.6.2.0740>15.6.2.0740</a> ASSEMBLER 
(<a href=dpans15.htm#15.3.2>15.3.2</a> The Forth dictionary);
<LI>source and format of display by 
<a href=dpans15.htm#15.6.1.2194>15.6.1.2194</a> SEE.
</ul>

<hr>
<a name=15.4.1.2>
<h4>15.4.1.2 Ambiguous conditions</h4>
</a>

<ul>
<LI>deleting the compilation word-list 
(<a href=dpans15.htm#15.6.2.1580>15.6.2.1580</a> FORGET);
<LI>fewer than u+1 items on control-flow stack 
(<a href=dpans15.htm#15.6.2.1015>15.6.2.1015</a> CSPICK,
<a href=dpans15.htm#15.6.2.1020>15.6.2.1020</a> CSROLL);
<LI>name can't be found 
(<a href=dpans15.htm#15.6.2.1580>15.6.2.1580</a> FORGET);
<LI>name not defined via 
<a href=dpans6.htm#6.1.1000>6.1.1000</a> CREATE 
(<a href=dpans15.htm#15.6.2.0470>15.6.2.0470</a> ;CODE);
<LI>
<a href=dpans6.htm#6.1.2033>6.1.2033</a> POSTPONE applied to 
<a href=dpans15.htm#15.6.2.2532>15.6.2.2532</a> [IF];
<LI>reaching the end of the input source before matching 
<a href=dpans15.htm#15.6.2.2531>15.6.2.2531</a> [ELSE] or 
<a href=dpans15.htm#15.6.2.2533>15.6.2.2533</a> [THEN] 
(<a href=dpans15.htm#15.6.2.2532>15.6.2.2532</a> [IF]);
<LI>removing a needed definition 
(<a href=dpans15.htm#15.6.2.1580>15.6.2.1580</a> FORGET).
</UL>
<P>

<hr>
<A name=15.4.1.3>
<H4>15.4.1.3 Other system documentation</H4>
</a>

<ul>
<li>no additional requirements.
</ul>
<P>

<hr>
<A name=15.4.2>
<H3>15.4.2 Program documentation</H3>
</a>

<hr>
<A name=15.4.2.1>
<H4>15.4.2.1 Environmental dependencies</H4>
</a>

<UL>
<LI>using the words 
<a href=dpans15.htm#15.6.2.0470>15.6.2.0470</a> ;CODE or 
<a href=dpans15.htm#15.6.2.0930>15.6.2.0930</a> CODE.
</ul>

<hr>
<A name=15.4.2.2>
<h4>15.4.2.2 Other program documentation</h4>
</a>
<ul>
<LI>no additional requirements.
</UL>

<P>

<hr>
<A name=15.5>
<H2>15.5 Compliance and labeling</H2>
</a>


<hr>
<A name=15.5.1>
<H3>15.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Programming-Tools word set</B> shall be
appended to the label of any Standard System that provides all of the
Programming-Tools word set.

<P>

The phrase <B>Providing name(s) from the Programming-Tools Extensions
word set</B> shall be appended to the label of any Standard System that
provides portions of the Programming-Tools Extensions word set.

<P>

The phrase <B>Providing the Programming-Tools Extensions word set</B>
shall be appended to the label of any Standard System that provides all
of the Programming-Tools and Programming-Tools Extensions word sets.

<P>

<hr>
<A name=15.5.2>
<H3>15.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Programming-Tools word set</B> shall be
appended to the label of Standard Programs that require the system to
provide the Programming-Tools word set.

<P>

The phrase <B>Requiring name(s) from the Programming-Tools Extensions
word set</B> shall be appended to the label of Standard Programs that
require the system to provide portions of the Programming-Tools
Extensions word set.

<P>

The phrase <B>Requiring the Programming-Tools Extensions word set</B>
shall be appended to the label of Standard Programs that require the
system to provide all of the Programming-Tools and Programming-Tools
Extensions word sets.

<P>

<hr>
<A name=15.6>
<H3>15.6 Glossary</H3>
</a>


<hr>
<A name=15.6.1>
<H3>15.6.1 Programming-Tools words</H3>
</a>


<hr>
<A name=15.6.1.0220>
<code>
15.6.1.0220 <b>.S</b>
</code>
</a>
<BR>
<B>dot-s</B> TOOLS
<BR>
<pre>
	( -- )
</pre>
<P>

Copy and display the values currently on the data stack.  The format of
the display is implementation-dependent.

<P>

.S may be implemented using pictured numeric output words.
Consequently, its use may corrupt the transient region identified by 
<a href=dpans6.htm#6.1.0040>#&gt;</a>.
<P>

<code>
See:
<a href=dpansa15.htm#A.15.6.1.0220>A.15.6.1.0220 .S</a> ,
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions.
</code>

<P>

<hr>
<A name=15.6.1.0600>
<code>
15.6.1.0600 <b>?</b>
</code>
</a>
<BR>
<B>question</B>      TOOLS
<BR>
<pre>
	( a-addr -- )
</pre>
<P>

Display the value stored at a-addr.
<P>

? may be implemented using pictured numeric output words.  Consequently,
its use may corrupt the transient region identified by 
<a href=dpans6.htm#6.1.0040>#&gt;</a>.
<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions
</code>

<P>

<hr>
<A name=15.6.1.1280>
<code>
15.6.1.1280 <b>DUMP</b>
</code>
</a>
<BR>
TOOLS
<BR>
<pre>
	( addr u -- )
</pre>
<P>

Display the contents of u consecutive addresses starting at addr.  The
format of the display is implementation dependent.

<P>

DUMP may be implemented using pictured numeric output words.
Consequently, its use may corrupt the transient region identified by 
<a href=dpans6.htm#6.1.0040>#&gt;</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions
</code>

<P>

<hr>
<A name=15.6.1.2194>
<code>
15.6.1.2194 <b>SEE</b>
</code>
</a>
<BR>
TOOLS
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Display a human-readable representation of the named word's definition.
The source of the representation (object-code decompilation, source
block, etc.) and the particular form of the display is implementation
defined.

<P>

SEE may be implemented using pictured numeric output words.
Consequently, its use may corrupt the transient region identified by 
<a href=dpans6.htm#6.1.0040>#&gt;</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions,
<a href=dpansa15.htm#A.15.6.1.2194>A.15.6.1.2194 SEE</a>
</code>

<P>

<hr>
<A name=15.6.1.2465>
<code>
15.6.1.2465 <b>WORDS</b>
</code>
</a>
<BR>
TOOLS
<BR>
<pre>
	( -- )
</pre>
<P>

List the definition names in the first word list of the search order.
The format of the display is implementation-dependent.

<P>

WORDS may be implemented using pictured numeric output words.
Consequently, its use may corrupt the transient region identified by 
<a href=dpans6.htm#6.1.0040>#&gt;</a>.
<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions,
<a href=dpansa15.htm#A.15.6.1.2465>A.15.6.1.2465 WORDS</a>
</code>

<P>

<hr>
<A name=15.6.2>
<H3>15.6.2 Programming-Tools extension words</H3>
</a>


<hr>
<A name=15.6.2.0470>
<code>
15.6.2.0470 <b>;CODE</b>
</code>
</a>
<BR>
<B>semicolon-code</B>        TOOLS EXT
<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<PRE>
        Compilation: ( C: colon-sys -- )
</PRE>
<P>

Append the run-time semantics below to the current definition.  End the
current definition, allow it to be found in the dictionary, and enter
interpretation state, consuming colon-sys.

<P>

Subsequent characters in the parse area typically represent source code
in a programming language, usually some form of assembly language.
Those characters are processed in an implementation-defined manner,
generating the corresponding machine code.  The process continues,
refilling the input buffer as needed, until an implementation-defined
ending sequence is processed.


<PRE>
        Run-time: ( -- ) ( R: nest-sys -- )
</PRE>

<P>

Replace the execution semantics of the most recent definition with the
name execution semantics given below.  Return control to the calling
definition specified by nest-sys.  An ambiguous condition exists if the
most recent definition was not defined with 
<a href=dpans6.htm#6.1.1000>CREATE</a> or a user-defined
word that calls CREATE.

<PRE>
        <i>name</i> Execution: ( i*x -- j*x )
</PRE>
<P>

Perform the machine code sequence that was generated following ;CODE.
<P>

<code>
See:    
<a href=dpansa15.htm#A.15.6.2.0470>A.15.6.2.0470 ;CODE</a> ,
<A href=dpans6.htm#6.1.1250>6.1.1250 DOES&gt;</a>
</code>

<P>

<hr>
<A name=15.6.2.0702>
<code>
15.6.2.0702 <b>AHEAD</b>
</code>
</a>
<BR>
TOOLS EXT
<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>

<PRE>
        Compilation: ( C: -- orig )
</PRE>

Put the location of a new unresolved forward reference orig onto the
control flow stack.  Append the run-time semantics given below to the
current definition.  The semantics are incomplete until orig is resolved
(e.g., by 
<a href=dpans6.htm#6.1.2270>THEN</a>).


<PRE>
        Run-time: ( -- )
</PRE>
<P>

Continue execution at the location specified by the resolution of orig.

<P>

<hr>
<A name=15.6.2.0740>
<code>
15.6.2.0740 <b>ASSEMBLER</b>
</code>
</a>
<BR>
TOOLS EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Replace the first word list in the search order with the ASSEMBLER word
list.
<P>

<code>
See:
<A href=dpans16.htm#16.>16.</a> The optional Search-Order word set
</code>

<P>

<hr>
<A name=15.6.2.0830>
<code>
15.6.2.0830 <b>BYE</b>
</code>
</a>
<BR>
TOOLS EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Return control to the host operating system, if any.
<P>


<hr>
<A name=15.6.2.0930>
<code>
15.6.2.0930 <b>CODE</b>
</code>
</a>
<BR>
TOOLS EXT
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters.  Parse name delimited by a space.  Create
a definition for name, called a <B>code definition</B>, with the
execution semantics defined below.

<P>

Subsequent characters in the parse area typically represent source code
in a programming language, usually some form of assembly language.
Those characters are processed in an implementation-defined manner,
generating the corresponding machine code.  The process continues,
refilling the input buffer as needed, until an implementation-defined
ending sequence is processed.


<PRE>
        <i>name</i> Execution: ( i*x -- j*x )
</PRE>
<P>

Execute the machine code sequence that was generated following CODE.
<P>

<code>
See:
<a href=dpansa15.htm#A.15.6.2.0930>A.15.6.2.0930 CODE</a> ,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing.
</code>

<P>

<hr>
<A name=15.6.2.1015>
<code>
15.6.2.1015 <b>CS-PICK</b>
</code>
</a>
<BR>
<B>c-s-pick</B>      TOOLS EXT
<BR>
<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( C: destu ... orig0|dest0 -- destu ... orig0|dest0 destu )( S: u -- )
</pre>
<P>

Remove u.  Copy destu to the top of the control-flow stack.  An
ambiguous condition exists if there are less than u+1 items, each of
which shall be an orig or dest, on the control-flow stack before CS-PICK
is executed.

<P>

If the control-flow stack is implemented using the data stack, u shall
be the topmost item on the data stack.

<p>
<code>
See:
<a href=dpansa15.htm#A.15.6.2.1015>A.15.6.2.1015 CS-PICK</a>
</code>
<p>


<hr>
<A name=15.6.2.1020>
<code>
15.6.2.1020 <b>CS-ROLL</b>
</code>
</a>
<BR>
<B>c-s-roll</B>      TOOLS EXT
<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( C: origu|destu origu-1|destu-1 ... orig0|dest0 --
                          origu-1|destu-1 ... orig0|dest0 origu|destu )( S: u -- )
</pre>
<P>

Remove u.  Rotate u+1 elements on top of the control-flow stack so that
origu|destu is on top of the control-flow stack.  An ambiguous condition
exists if there are less than u+1 items, each of which shall be an orig
or dest, on the control-flow stack before CS-ROLL is executed.

<P>

If the control-flow stack is implemented using the data stack, u shall
be the topmost item on the data stack.

<p>
<code>
See:
<a href=dpansa15.htm#A.15.6.2.1020>A.15.6.2.1020 CS-ROLL</a>
</code>
<p>


<hr>
<A name=15.6.2.1300>
<code>
15.6.2.1300 <b>EDITOR</b>
</code>
</a>
<BR>
TOOLS EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Replace the first word list in the search order with the EDITOR word
list.

<P>

<code>
See:
<A href=dpans16.htm#16.>16.</a> The Optional Search-Order Word Set
</code>

<P>

<hr>
<A name=15.6.2.1580>
<code>
15.6.2.1580 <b>FORGET</b>
</code>
</a>
<BR>
TOOLS EXT
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters.  Parse name delimited by a space.  Find
name, then delete name from the dictionary along with all words added to
the dictionary after name.  An ambiguous condition exists if name cannot
be found.

<P>

If the Search-Order word set is present, FORGET searches the compilation
word list.  An ambiguous condition exists if the compilation word list
is deleted.

<P>

An ambiguous condition exists if FORGET removes a word required for
correct execution.

<P>

<b>Note:</b> This word is obsolescent and is included as a concession to
existing implementations.

<P>

<code>
See:
<a href=dpansa15.htm#A.15.6.2.1580>A.15.6.2.1580 FORGET</a> ,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpans6.htm#6.2.1850>6.2.1850 MARKER</a>
</code>
<P>

<hr>
<A name=15.6.2.2250>
<code>
15.6.2.2250 <b>STATE</b>
</code>
</a>
<BR>
TOOLS EXT
<BR>
<pre>
	( -- a-addr )
</pre>
<P>

Extend the semantics of 
<a href=dpans6.htm#6.1.2250>6.1.2250</a> STATE to allow 
<a href=dpans15.htm#15.6.2.0470>;CODE</a> to change the
value in STATE.  A program shall not directly alter the contents of
STATE.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans6.htm#6.1.0450>6.1.0450 :</a> ,
<A href=dpans6.htm#6.1.0460>6.1.0460 ;</a> ,
<A href=dpans6.htm#6.1.0670>6.1.0670 ABORT</a> ,
<A href=dpans6.htm#6.1.2050>6.1.2050 QUIT</a> ,
<A href=dpans6.htm#6.1.2500>6.1.2500 [</a> ,
<A href=dpans6.htm#6.1.2540>6.1.2540 ]</a> ,
<A href=dpans6.htm#6.2.0455>6.2.0455 :NONAME</a>
</code>

<P>

<hr>
<A name=15.6.2.2531>
<code>
15.6.2.2531 <b>[ELSE]</b>
</code>
</a>
<BR>
<B>bracket-else</B>  TOOLS EXT
<BR>
<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<PRE>
        Execution: ( <B>"&lt;spaces&gt;name"</b> ... -- )
</PRE>
<P>

Skipping leading spaces, parse and discard space-delimited words from
the parse area, including nested occurrences of 
<a href=dpans15.htm#15.6.2.2532>[IF]</a> ...  
<a href=dpans15.htm#15.6.2.2533>[THEN]</a> and
[IF] ...  [ELSE] ...  [THEN], until the word [THEN] has been parsed and
discarded.  If the parse area becomes exhausted, it is refilled as with
<a href=dpans6.htm#6.2.2125>REFILL</a>.  
[ELSE] is an immediate word.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa15.htm#A.15.6.2.2531>A.15.6.2.2531 [ELSE]</a>
</code>

<P>

<hr>
<A name=15.6.2.2532>
<code>
15.6.2.2532 <b>[IF]</b>
</code>
</a>
<BR>
<B>bracket-if</B>    TOOLS EXT
<BR>
<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
	Execution: ( flag | flag <B>"&lt;spaces&gt;name"</b> ... -- )
</pre>
<P>

If flag is true, do nothing.  Otherwise, skipping leading spaces, parse
and discard space-delimited words from the parse area, including nested
occurrences of [IF] ...  
<a href=dpans15.htm#15.6.2.2533>[THEN]</a> and [IF] ...  
<a href=dpans15.htm#15.6.2.2531>[ELSE]</a> ...  [THEN], until
either the word [ELSE] or the word [THEN] has been parsed and discarded.
If the parse area becomes exhausted, it is refilled as with 
<a href=dpans6.htm#6.2.2125>REFILL</a>.
[IF] is an immediate word.

<P>

An ambiguous condition exists if [IF] is 
<a href=dpans6.htm#6.1.2033>POSTPONE</a>d, or if the end of the
input buffer is reached and cannot be refilled before the terminating
[ELSE] or [THEN] is parsed.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa15.htm#A.15.6.2.2532>A.15.6.2.2532 [IF]</a>
</code>

<P>

<hr>
<A name=15.6.2.2533>
<code>
15.6.2.2533 <b>[THEN]</b>
</code>
</a>
<BR>
<B>bracket-then</B>  TOOLS EXT
<BR>
<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
	Execution: ( -- )
</pre>
<P>

Does nothing.  [THEN] is an immediate word.
<P>
<code>
See:
<a href=dpansa15.htm#A.15.6.2.2533>A.15.6.2.2533 [THEN]</a>
</code>
<p>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans16.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans16.htm/    851247300   500   0     100644  13344     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans15.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans17.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=16.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>16. The optional Search-Order word set</H1>

<p>
<code>
See:
<a href=dpansa16.htm>A.16</a> The optional Search-Order word set
</code>
<p>

<hr>
<A name=16.1>
<H2>16.1 Introduction</H2>
</a>

<hr>
<A name=16.2>
<H2>16.2 Additional terms and notation</H2>
</a>

<DL><DT><B>compilation word list:</B>
<DD>The word list into which new definition names are
placed.

<DT><B>search order:</B>
<DD>A list of word lists specifying the order in which the
dictionary will be searched.</DL>

<p>
<code>
See:
<a href=dpansa16.htm#A.16.2>A.16.2</a> Additional terms
</code>
<p>

<hr>
<A name=16.3>
<H2>16.3 Additional usage requirements</H2>
</a>

<hr>
<A name=16.3.1>
<H3>16.3.1 Data types</H3>
</a>

Word list identifiers are implementation-dependent single-cell values
that identify word lists.
<P>

Append table 16.1 to 
<a href=dpans3.htm#table.3.1>table 3.1</a>.
<P>

Table 16.1 - Data types
<P>

<PRE>
Symbol  Data type               Size on stack
------  ---------               -------------
wid     word list identifiers   1 cell
</PRE>
<P>

<code>
See:  
<A href=dpans3.htm#3.1>3.1</a> Data types,
<A href=dpans3.htm#3.4.2>3.4.2</a> Finding definition names,
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter.
</code>
<P>

<hr>
<A name=16.3.2>
<H3>16.3.2 Environmental queries</H3>
</a>

Append table 16.2 to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 16.2 - Environmental query strings
<P>

<PRE>
String            Value data type  Constant?  Meaning
------            ---------------  ---------  -------
SEARCH-ORDER      flag             no         search-order word set present
SEARCH-ORDER-EXT  flag             no         search-order extensions word set present
WORDLISTS         n                yes        maximum number of word lists usable
                                                in the search order

</PRE>

<P>

<hr>
<A name=16.3.3>
<H3>16.3.3 Finding definition names</H3>
</a>

When searching a word list for a definition name, the system shall
search each word list from its last definition to its first.  The search
may encompass only a single word list, as with 
<a href=dpans16.htm#16.6.1.2192>SEARCH-WORDLIST</a>, or all
the word lists in the search order, as with the text interpreter and
<a href=dpans6.htm#6.1.1550>FIND</a>.

<P>

Changing the search order shall only affect the subsequent finding of
definition names in the dictionary.

<P>

A system with the Search-Order word set shall allow at least eight word
lists in the search order.

<P>

An ambiguous condition exists if a program changes the compilation word
list during the compilation of a definition or before modification of
the behavior of the most recently compiled definition with 
<a href=dpans15.htm#15.6.2.0470>;CODE</a>, 
<a href=dpans6.htm#6.1.1250>DOES></a>,
or 
<a href=dpans6.htm#6.1.1710>IMMEDIATE</a>.

<P>

A program that requires more than eight word lists in the search order
has an environmental dependency.

<P>

<code>
See:
<A href=dpans3.htm#3.4.2>3.4.2</a> Finding definition names,
<a href=dpansa16.htm#A.16.3.3>A.16.3.3</a> Finding definition names.
</code>
<P>

<hr>
<A name=16.3.4>
<H3>16.3.4 Contiguous regions</H3>
</a>

The regions of data space produced by the operations described in
<a href=dpans3.htm#3.3.3.2>3.3.3.2</a> 
Contiguous regions may be non-contiguous if 
<a href=dpans16.htm#16.6.1.2460>WORDLIST</a> is executed
between allocations.

<P>

<hr>
<A name=16.4>
<H2>16.4 Additional documentation requirements</H2>
</a>

<hr>
<A name=16.4.1>
<H3>16.4.1 System documentation</H3>
</a>

<hr>
<A name=16.4.1.1>
<H4>16.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>maximum number of word lists in the search order 
(<a href=dpans16.htm#16.3.3>16.3.3</a> Finding definition names, 
<a href=dpans16.htm#16.6.1.2197>16.6.1.2197</a> SET-ORDER);
<LI>minimum search order 
(<a href=dpans16.htm#16.6.1.2197>16.6.1.2197</a> SET-ORDER, 
<a href=dpans16.htm#16.6.2.1965>16.6.2.1965</a> ONLY).
</UL>
<P>

<hr>
<A name=16.4.1.2>
<H4>16.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI>changing the compilation word list 
(<a href=dpans16.htm#16.3.3>16.3.3</a> Finding definition names);
<LI>search order empty 
(<a href=dpans16.htm#16.6.2.2037>16.6.2.2037</a> PREVIOUS);
<LI>too many word lists in search order 
(<a href=dpans16.htm#16.6.2.0715>16.6.2.0715</a> ALSO).
</ul>

<hr>
<a name=16.4.1.3>
<h4>16.4.1.3 Other system documentation</h4>
</a>
<ul>
<li>no additional requirements.
</ul>


<hr>
<a name=16.4.2>
<h3>16.4.2 Program documentation</h3>
</a>


<hr>
<A name=16.4.2.1>
<H4>16.4.2.1 Environmental dependencies</H4>
</a>

<UL>
<LI>requiring more than eight word-lists in the search order 
(<a href=dpans16.htm#16.3.3>16.3.3</a> Finding definition names).
</UL>


<hr>
<A name=16.4.2.2>
<H4>16.4.2.2 Other program documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>

<hr>
<A name=16.5>
<H2>16.5 Compliance and labeling</H2>
</a>

<hr>
<A name=16.5.1>
<H3>16.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Search-Order word set</B> shall be appended
to the label of any Standard System that provides all of the
Search-Order word set.

<P>

The phrase <B>Providing name(s) from the Search-Order Extensions word
set</B> shall be appended to the label of any Standard System that
provides portions of the Search-Order Extensions word set.

<P>

The phrase <B>Providing the Search-Order Extensions word set</B> shall
be appended to the label of any Standard System that provides all of the
Search-Order and Search-Order Extensions word sets.

<P>

<hr>
<A name=16.5.2>
<H3>16.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Search-Order word set</B> shall be appended
to the label of Standard Programs that require the system to provide the
Search-Order word set.

<P>

The phrase <B>Requiring name(s) from the Search-Order Extensions word
set</B> shall be appended to the label of Standard Programs that require
the system to provide portions of the Search-Order Extensions word set.

<P>

The phrase <B>Requiring the Search-Order Extensions word set</B> shall
be appended to the label of Standard Programs that require the system to
provide all of the Search-Order and Search-Order Extensions word sets.

<P>

<hr>
<A name=16.6>
<H2>16.6 Glossary</H2>
</a>

<hr>
<A name=16.6.1>
<H3>16.6.1 Search-Order words</H3>
</a>

<hr>
<A name=16.6.1.1180>
<code>
16.6.1.1180 <b>DEFINITIONS</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( -- )
</pre>
<P>

Make the compilation word list the same as the first word list in the
search order.  Specifies that the names of subsequent definitions will
be placed in the compilation word list.  Subsequent changes in the
search order will not affect the compilation word list.

<P>

<code>
See:
<A href=dpans16.htm#16.3.3>16.3.3</a> Finding Definition Names
</code>

<P>

<hr>
<A name=16.6.1.1550>
<code>
16.6.1.1550 <b>FIND</b>
</code>
</a>
<BR>
SEARCH
<BR>
<P>

Extend the semantics of 
<a href=dpans6.htm#6.1.1550>6.1.1550</a> FIND to be:
<P>

<pre>
	( c-addr -- c-addr 0  |  xt 1  |  xt -1 )
</pre>
<P>

Find the definition named in the counted string at c-addr.  If the
definition is not found after searching all the word lists in the search
order, return c-addr and zero.  If the definition is found, return xt.
If the definition is immediate, also return one (1); otherwise also
return minus-one (-1).  For a given string, the values returned by FIND
while compiling may differ from those returned while not compiling.

<P>

<code>
See:
<A href=dpans3.htm#3.4.2>3.4.2</a> Finding definition names,
<A href=dpans6.htm#6.1.0070>6.1.0070 '</a> ,
<A href=dpans6.htm#6.1.2033>6.1.2033 POSTPONE</a> ,
<A href=dpans6.htm#6.1.2510>6.1.2510 [']</a> ,
<A href=dpansd.htm#D.6.7>D.6.7</a> Immediacy.
</code>

<P>

<hr>
<A name=16.6.1.1595>
<code>
16.6.1.1595 <b>FORTH-WORDLIST</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( -- wid )
</pre>
<P>

Return wid, the identifier of the word list that includes all standard
words provided by the implementation.  This word list is initially the
compilation word list and is part of the initial search order.

<P>

<hr>
<A name=16.6.1.1643>
<code>
16.6.1.1643 <b>GET-CURRENT</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( -- wid )
</pre>
<P>

Return wid, the identifier of the compilation word list.
<P>

<hr>
<A name=16.6.1.1647>
<code>
16.6.1.1647 <b>GET-ORDER</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( -- widn ... wid1 n )
</pre>
<P>

Returns the number of word lists n in the search order and the word list
identifiers widn ...  wid1 identifying these word lists.  wid1
identifies the word list that is searched first, and widn the word list
that is searched last.  The search order is unaffected.

<P>
<code>
See:
<a href=a0002.htm>RFI 0002</a>
</code>
<p>

<hr>
<A name=16.6.1.2192>
<code>
16.6.1.2192 <b>SEARCH-WORDLIST</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( c-addr u wid -- 0 | xt 1 | xt -1 )
</pre>
<P>

Find the definition identified by the string c-addr u in the word list
identified by wid.  If the definition is not found, return zero.  If the
definition is found, return its execution token xt and one (1) if the
definition is immediate, minus-one (-1) otherwise.

<p>
<code>
See:
<a href=dpansa16.htm#A.16.6.1.2192>A.16.6.1.2192 SEARCH-WORDLIST</a>
</code>
<p>

<hr>
<A name=16.6.1.2195>
<code>
16.6.1.2195 <b>SET-CURRENT</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( wid -- )
</pre>
<P>

Set the compilation word list to the word list identified by wid.

<P>

<hr>
<A name=16.6.1.2197>
<code>
16.6.1.2197 <b>SET-ORDER</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( widn ... wid1 n -- )
</pre>
<P>

Set the search order to the word lists identified by widn ...  wid1.
Subsequently, word list wid1 will be searched first, and word list widn
searched last.  If n is zero, empty the search order.  If n is minus
one, set the search order to the implementation-defined minimum search
order.  The minimum search order shall include the words 
<a href=dpans16.htm#16.6.1.1595>FORTH-WORDLIST</a>
and SET-ORDER.  A system shall allow n to be at least eight.

<P>
<code>
See:
<a href=a0002.htm>RFI 0002</a>
</code>
<P>

<hr>
<A name=16.6.1.2460>
<code>
16.6.1.2460 <b>WORDLIST</b>
</code>
</a>
<BR>
SEARCH
<BR>
<pre>
	( -- wid )
</pre>
<P>

Create a new empty word list, returning its word list identifier wid.
The new word list may be returned from a pool of preallocated word lists
or may be dynamically allocated in data space.  A system shall allow the
creation of at least 8 new word lists in addition to any provided as
part of the system.

<P>

<hr>
<A name=16.6.2>
<H3>16.6.2 Search-Order extension words</H3>
</a>


<hr>
<A name=16.6.2.0715>
<code>
16.6.2.0715 <b>ALSO</b>
</code>
</a>
<BR>
SEARCH EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Transform the search order consisting of widn, ...  wid2, wid1 (where
wid1 is searched first) into widn, ...  wid2, wid1, wid1.  An ambiguous
condition exists if there are too many word lists in the search order.

<p>
<code>
See:
<a href=dpansa16.htm#A.16.6.2.0715>A.16.6.2.0715 ALSO</a> ,
<a href=a0002.htm>RFI 0002</a>
</code>
<p>


<hr>
<A name=16.6.2.1590>
<code>
16.6.2.1590 <b>FORTH</b>
</code>
</a>
<BR>
SEARCH EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Transform the search order consisting of widn, ...  wid2, wid1 (where
wid1 is searched first) into widn, ...  wid2, 
wid <a href=dpans16.htm#16.6.1.1595>FORTH-WORDLIST</a>.

<P>

<hr>
<A name=16.6.2.1965>
<code>
16.6.2.1965 <b>ONLY</b>
</code>
</a>
<BR>
SEARCH EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Set the search order to the implementation-defined minimum search order.
The minimum search order shall include the words 
<a href=dpans16.htm#16.6.1.1595>FORTH-WORDLIST</a> and
<a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>.

<P>
<code>
See:
<a href=a0002.htm>RFI 0002</a>
</code>
<p>

<hr>
<A name=16.6.2.1985>
<code>
16.6.2.1985 <b>ORDER</b>
</code>
</a>
<BR>
SEARCH EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Display the word lists in the search order in their search order
sequence, from first searched to last searched.  Also display the word
list into which new definitions will be placed.  The display format is
implementation dependent.

<P>

ORDER may be implemented using pictured numeric output words.
Consequently, its use may corrupt the transient region identified by 
<a href=dpans6.htm#6.1.0040>#&gt;</a>.
<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other Transient Regions
</code>
<P>

<hr>
<A name=16.6.2.2037>
<code>
16.6.2.2037 <b>PREVIOUS</b>
</code>
</a>
<BR>
SEARCH EXT
<BR>
<pre>
	( -- )
</pre>
<P>

Transform the search order consisting of widn, ...  wid2, wid1 (where
wid1 is searched first) into widn, ...  wid2.  An ambiguous condition
exists if the search order was empty before PREVIOUS was executed.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans17.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans17.htm/    851247300   500   0     100644  6946      `
<HTML>
<HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>
<body>
<table width=100%>
<tr>
<td align=left>
<a href=dpans16.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa1.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=17.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>


<H1>17. The optional String word set</H1>


<hr>
<A name=17.1>
<H2>17.1 Introduction</H2>
</a>


<hr>
<A name=17.2>
<H2>17.2 Additional terms and notation</H2>
</a>

None.
<P>


<hr>
<A name=17.3>
<H2>17.3 Additional usage requirements</H2>
</a>

Append table 17.1 to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 17.1 - Environmental query strings


<PRE>
String         Value data type    Constant?   Meaning
------         ---------------    ---------   -------
STRING          flag              no          string word set present
STRING-EXT      flag              no          string extensions word set present
</PRE>
<P>


<hr>
<A name=17.4>
<H2>17.4 Additional documentation requirements</H2>
</a>

None.
<P>

<hr>
<A name=17.5>
<H2>17.5 Compliance and labeling</H2>
</a>

<hr>
<A name=17.5.1>
<H3>17.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the String word set</B> shall be appended to the
label of any Standard System that provides all of the String word set.
<P>

The phrase <B>Providing name(s) from the String Extensions word set</B>
shall be appended to the label of any Standard System that provides
portions of the String Extensions word set.
<P>

The phrase <B>Providing the String Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
String and String Extensions word sets.
<P>


<hr>
<A name=17.5.2>
<H3>17.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the String word set</B> shall be appended to the
label of Standard Programs that require the system to provide the String
word set.

<P>

The phrase <B>Requiring name(s) from the String Extensions word set</B>
shall be appended to the label of Standard Programs that require the
system to provide portions of the String Extensions word set.

<P>

The phrase <B>Requiring the String Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the String and String Extensions word sets.


<P>

<hr>
<A name=17.6>
<H2>17.6 Glossary</H2>
</a>


<hr>
<A name=17.6.1>
<H3>17.6.1 String words</H3>
</a>


<hr>
<A name=17.6.1.0170>
<code>
17.6.1.0170 <b>-TRAILING</b>
</code>
</a>
<BR>
<B>dash-trailing</B> STRING
<BR>
<pre>
	( c-addr u1 -- c-addr u2 )
</pre>
<P>

If u1 is greater than zero, u2 is equal to u1 less the number of spaces
at the end of the character string specified by c-addr u1.  If u1 is
zero or the entire string consists of spaces, u2 is zero.

<P>

<hr>
<A name=17.6.1.0245>
<code>
17.6.1.0245 <b>/STRING</b>
</code>
</a>
<BR>
<B>slash-string</B>  STRING
<BR>
<pre>
	( c-addr1 u1 n -- c-addr2 u2 )
</pre>
<P>

Adjust the character string at c-addr1 by n characters.  The resulting
character string, specified by c-addr2 u2, begins at c-addr1 plus n
characters and is u1 minus n characters long.

<P>
<code>
See:
<a href=dpansa17.htm#A.17.6.1.0245>A.17.6.1.0245 /STRING</a>
</code>
<p>

<hr>
<A name=17.6.1.0780>
<code>
17.6.1.0780 <b>BLANK</b>
</code>
</a>
<BR>
STRING
<BR>
<pre>
	( c-addr u -- )
</pre>
<P>

If u is greater than zero, store the character value for space in u
consecutive character positions beginning at c-addr.
<P>

<hr>
<A name=17.6.1.0910>
<code>
17.6.1.0910 <b>CMOVE</b>
</code>
</a>
<BR>
<B>c-move</B>        STRING
<BR>
<pre>
	( c-addr1 c-addr2 u -- )
</pre>
<P>

If u is greater than zero, copy u consecutive characters from the data
space starting at c-addr1 to that starting at c-addr2, proceeding
character-by-character from lower addresses to higher addresses.

<P>
<code>
See:
<a href=dpansa17.htm#A.17.6.1.0910>A.17.6.1.0910 CMOVE</a> ,
<a href=dpans17.htm#17.6.1.0920>17.6.1.0920 CMOVE&gt;</a>
</code>
<p>


<hr>
<A name=17.6.1.0920>
<code>
17.6.1.0920 <b>CMOVE&gt;</b>
</code>
</a>
<BR>
<B>c-move-up</B>     STRING
<BR>
<pre>
	( c-addr1 c-addr2 u -- )
</pre>
<P>

If u is greater than zero, copy u consecutive characters from the data
space starting at c-addr1 to that starting at c-addr2, proceeding
character-by-character from higher addresses to lower addresses.

<P>
<code>
See:
<a href=dpans17.htm#17.6.1.0910>17.6.1.0910 CMOVE</a> ,
<a href=dpansa17.htm#A.17.6.1.0920>A.17.6.1.0920 CMOVE&gt;</a>
</code>
<p>


<hr>
<A name=17.6.1.0935>
<code>
17.6.1.0935 <b>COMPARE</b>
</code>
</a>
<BR>
STRING
<BR>
<pre>
	( c-addr1 u1 c-addr2 u2 -- n )
</pre>
<P>

Compare the string specified by c-addr1 u1 to the string specified by
c-addr2 u2.  The strings are compared, beginning at the given addresses,
character by character, up to the length of the shorter string or until
a difference is found.  If the two strings are identical, n is zero.  If
the two strings are identical up to the length of the shorter string, n
is minus-one (-1) if u1 is less than u2 and one (1) otherwise.  If the
two strings are not identical up to the length of the shorter string, n
is minus-one (-1) if the first non-matching character in the string
specified by c-addr1 u1 has a lesser numeric value than the
corresponding character in the string specified by c-addr2 u2 and one
(1) otherwise.

<P>
<code>
See:
<a href=dpansa17.htm#A.17.6.1.0935>A.17.6.1.0935 COMPARE</a>
</code>
<p>


<hr>
<A name=17.6.1.2191>
<code>
17.6.1.2191 <b>SEARCH</b>
</code>
</a>
<BR>
STRING
<BR>
<pre>
	( c-addr1 u1 c-addr2 u2 -- c-addr3 u3 flag )
</pre>
<P>

Search the string specified by c-addr1 u1 for the string specified by
c-addr2 u2.  If flag is true, a match was found at c-addr3 with u3
characters remaining.  If flag is false there was no match and c-addr3
is c-addr1 and u3 is u1.

<P>
<code>
See:
<a href=dpansa17.htm#A.17.6.1.2191>A.17.6.1.2191 SEARCH</a>
</code>
<p>


<hr>
<A name=17.6.1.2212>
<code>
17.6.1.2212 <b>SLITERAL</b>
</code>
</a>
<BR>
STRING
<BR>
<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<PRE>
        Compilation: ( c-addr1 u -- )
</PRE>

<P>

Append the run-time semantics given below to the current definition.
<P>


<PRE>
        Run-time:       ( -- c-addr2 u )
</PRE>
<P>

Return c-addr2 u describing a string consisting of the characters
specified by c-addr1 u during compilation.  A program shall not alter
the returned string.

<P>
<code>
See:
<a href=dpansa17.htm#A.17.6.1.2212>A.17.6.1.2212 SLITERAL</a>
</code>
<p>


<hr>
<A name=17.6.2>
<H3>17.6.2 String extension words</H3>
</a>

None
<P>


<A href=dpans.htm#toc><IMG   src="up.gif" ></A>
Table of Contents 
<BR>
<A href=dpansa1.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans2.htm/     851247000   500   0     100644  15601     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans1.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans3.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=2.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>2. Terms, notation, and references</H1>

The phrase <B>See:</B> is used throughout this Standard to direct the reader to
other sections of the Standard that have a direct bearing on the current
section.

<P>

In this Standard, <B>shall</B> states a requirement on a system or
program; conversely, <B>shall not</B> is a prohibition; <B>need not</B>
means <B>is not required to</B>; <B>should</B> describes a
recommendation of the Standard; and <B>may</B>, depending on context,
means <B>is allowed to</B> or <B>might happen</B>.

<P>

Throughout the Standard,
typefaces are used in the following manner:

<UL>
<LI>This proportional
serif typeface is used for text, with italic used
for symbols and the first appearance of new terms;
<LI>A bold
proportional sans-serif typeface is used for headings;
<LI>A bold
monospaced serif typeface is used for Forth-language text.
</UL>

<P>

<hr>
<A name=2.1>
<H2>2.1 Definitions of terms</H2>
</a>

Terms defined in this section are used generally throughout this Standard.
Additional terms specific to individual word sets are defined in those word
sets.  Other terms are defined at their first appearance, indicated by italic
type.  Terms not defined in this Standard are to be construed according to the
Dictionary for Information Systems, ANSI X3.172-1990.

<P>

<DL><DT><B>address unit:</B>  <DD>Depending on context, either 1) the units
into which a Forth
address space is divided for the purposes of locating data objects such as
characters and variables; 2) the physical memory storage elements
corresponding to those units; 3) the contents of such a memory storage
element; or 4) the units in which the length of a region of memory is
expressed.

<DT><B>aligned address:</B>  <DD>The address of a memory location at which a
character, cell,
cell pair, or double-cell integer can be accessed.

<DT><B>ambiguous condition:</B>  <DD>A circumstance for which this Standard
does not
prescribe a specific behavior for Forth systems and programs.

<P>

Ambiguous conditions include such things as the absence of a needed delimiter
while parsing, attempted access to a nonexistent file, or attempted use of a
nonexistent word.  An ambiguous condition also exists when a Standard word is
passed values that are improper or out of range.

<DT><B>cell:</B>
<DD>The primary unit of information in the architecture of a Forth system.

<DT><B>cell pair:</B>
<DD>Two cells that are treated as a single unit.

<DT><B>character:</B>
<DD>Depending on context, either 1) a storage unit capable of holding
a character; or 2) a member of a character set.

<DT><B>character-aligned address:</B>
<DD>The address of a memory location at which a
character can be accessed.

<DT><B>character string:</B>
<DD>Data space that is associated with a sequence of
consecutive character-aligned addresses.  Character strings usually
contain text.  Unless otherwise indicated, the term <B>string</B> means
<B>character string</B>.

<DT><B>code space:</B>
<DD>The logical area of the dictionary in which word semantics are
implemented.

<DT><B>compile:</B>
<DD>To transform
source code into dictionary definitions.

<DT><B>compilation semantics:</B>
<DD>The behavior of a Forth definition when its name is
encountered by the text interpreter in compilation state.

<DT><B>counted string:</B>
<DD>A data structure consisting of one character containing a
length followed by zero or more contiguous data characters.  Normally, counted
strings contain text.

<DT><B>cross compiler:</B>
<DD>A system that compiles a program for later execution in
an environment that may be physically and logically different from the
compiling environment.  In a cross compiler, the term <B>host</B>
applies to the compiling environment, and the term <B>target</B> applies
to the run-time environment.

<DT><B>current definition:</B>
<DD>The definition whose compilation has been started but not
yet ended.

<DT><B>data field:</B>
<DD>The data space
associated with a word defined via 
<a href=dpans6.htm#6.1.1000>CREATE</a>.

<DT><B>data space:</B>
<DD>The logical
area of the dictionary that can be accessed.

<DT><B>data-space pointer:</B>
<DD>The address of the next available data space location,
i.e., the value returned by 
<a href=dpans6.htm#6.1.1650>HERE</a>.

<DT><B>data stack:</B>
<DD>A stack that may be used for passing parameters between
definitions.  When there is no possibility of confusion, the data stack is
referred to as <B>the stack</B>.  Contrast with return stack.

<DT><B>data type:</B>
<DD>An identifier
for the set of values that a data object may have.

<DT><B>defining word:</B>
<DD>A Forth word
that creates a new definition when executed.

<DT><B>definition:</B>
<DD>A Forth execution
procedure compiled into the dictionary.

<DT><B>dictionary:</B>
<DD>An extensible structure that contains definitions and associated
data space.

<DT><B>display:</B>
<DD>To send one or more
characters to the user output device.

<DT><B>environmental dependencies:</B>
<DD>A program's implicit assumptions about a Forth
system's implementation options or underlying hardware.  For example, a
program that assumes a cell size greater than 16 bits is said to have an
environmental dependency.

<DT><B>execution semantics:</B>
<DD>The behavior
of a Forth definition when it is executed.

<DT><B>execution token:</B>
<DD>A value that identifies the execution semantics of a
definition.

<DT><B>find:</B>
<DD>To search the
dictionary for a definition name matching a given string.

<DT><B>immediate word:</B>
<DD>A Forth word whose compilation semantics are to perform its
execution semantics.

<DT><B>implementation defined:</B>
<DD>Denotes system behaviors or features that must be
provided and documented by a system but whose further details are not
prescribed by this Standard.

<DT><B>implementation dependent:</B>
<DD>Denotes system behaviors or features that must be
provided by a system but whose further details are not prescribed by this
Standard.

<DT><B>input buffer:</B>
<DD>A region of memory containing the sequence of characters from
the input source that is currently accessible to a program.

<DT><B>input source:</B>
<DD>The device, file, block, or other entity that supplies
characters to refill the input buffer.

<DT><B>input source specification:</B>
<DD>A set of information describing a particular
state of the input source, input buffer, and parse area. This information is
sufficient, when saved and restored properly, to enable the nesting of parsing
operations on the same or different input sources.

<DT><B>interpretation semantics:</B>
<DD>The behavior of a Forth definition when its name is
encountered by the text interpreter in interpretation state.

<dt><b>initiation semantics:</b> 
<dd>The behavior of a Forth definition, or of the portion of a Forth definition 
following <a href=dpans6.htm#6.1.1250>DOES></a>, when it begins execution. 

<DT><B>keyboard event:</B>
<DD>A value received by the system denoting a user action at the
user input device.  The term <B>keyboard</B> in this document does not exclude
other types of user input devices.

<DT><B>line:</B>
<DD>A sequence of characters followed by an actual or implied line
terminator.

<DT><B>name space:</B>
<DD>The logical area of the dictionary in which definition names are
stored.

<DT><B>number:</B>
<DD>In this Standard, <B>number</B> used without other qualification
means <B>integer</B>.  Similarly, <B>double number</B> means
<B>double-cell integer</B>.

<DT><B>parse:</B>
<DD>To select and exclude a character string from the parse area using a
specified set of delimiting characters, called delimiters.

<DT><B>parse area:</B>
<DD>The portion of the input buffer that has not yet been parsed, and
is thus available to the system for subsequent processing by the text
interpreter and other parsing operations.

<DT><B>pictured-numeric output:</B>
<DD>A number display format in which the number is
converted using Forth words that resemble a symbolic <B>picture</B> of
the desired output.

<DT><B>program:</B>
<DD>A complete specification of execution to achieve a specific function
(application task) expressed in Forth source code form.

<DT><B>receive:</B>
<DD>To obtain characters
from the user input device.

<DT><B>return stack:</B>
<DD>A stack that may be used for program execution nesting, do-loop
execution, temporary storage, and other purposes.

<DT><B>standard word:</B>
<DD>A named Forth
procedure, formally specified in this Standard.

<DT><B>user input device:</B>
<DD>The input device currently selected as the source of
received data, typically a keyboard.

<DT><B>user output device:</B>
<DD>The output device currently selected as the destination
of display data.

<DT><B>variable:</B>
<DD>A named region of data space located and accessed by its memory
address.

<DT><B>word:</B>
<DD>Depending on context, either 1) the name of a Forth definition; or 2) a
parsed sequence of non-space characters, which could be the name of a Forth
definition.

<DT><B>word list:</B>
<DD>A list of associated Forth definition names that may be examined
during a dictionary search.

<DT><B>word set:</B>
<DD>A set of Forth definitions grouped together in this Standard under
a name indicating some shared aspect, typically their common functional
area.</DL>

<p>
<code>
See:
<a href=dpansa2.htm#A.2.1>A.2.1</a> Definition of terms,
<a href=a0005.htm>RFI 0005</a> Initiation semantics,
<a href=a0007.htm>RFI 0007</a> Distinction between <em>immediacy</em> and <em>special compilation semantics</em>.
</code>
<p>

<hr>
<A name=2.2>
<H3>2.2 Notation</H3>
</a>



<hr>
<A name=2.2.1>
<H3>2.2.1 Numeric notation</H3>
</a>

Unless otherwise stated, all references to numbers apply to signed single-cell
integers.  The inclusive range of values is shown as {from...to}.  The
allowable range for the contents of an address is shown in double braces,
particularly for the contents of variables, e.g., 
<a href=dpans6.htm#6.1.0750>BASE</a> {{2...36}}.

<P>

<hr>
<A name=2.2.2>
<H3>2.2.2 Stack notation</H3>
</a>

Stack parameters input to and output from a definition are described using the
notation:


<PRE>

( stack-id  before -- after )

</PRE>

<P>

where stack-id specifies which stack is being described, before represents the
stack-parameter data types before execution of the definition and after
represents them after execution.  The symbols used in before and after are
shown in 
<a href=dpans3.htm#table.3.1>table 3.1</a>.

<P>

The control-flow-stack stack-id is <B>C:</B>, the data-stack stack-id is
<B>S:</B>, and the return-stack stack-id is <B>R:</B>.  When there is no
confusion, the data-stack stack-id may be omitted.

<P>

When there are alternate after representations, they are described by
<B>after1 | after2</B>.  The top of the stack is to the right.  Only
those stack items required for or provided by execution of the
definition are shown.

<p>
<code>
See:
<a href=dpansa2.htm#A.2.2.2>A.2.2.2</a> Stack notation
</code>
<p>


<hr>
<A name=2.2.3>
<H3>2.2.3 Parsed-text notation</H3>
</a>

If, in addition to using stack parameters, a definition parses text,
that text is specified by an abbreviation from table 2.1, shown
surrounded by double-quotes and placed between the before parameters and
the <B>--</B> separator in the first stack described, e.g.,


<PRE>
( S: before <B>"parsed-text-abbreviation"</B> -- after ).
</PRE>

<P>

<a name=table.2.1>
Table 2.1 - Parsed text abbreviations
</a>

<P>


<PRE>
Abbreviation    Description
------------    -----------
&lt;char&gt;          the delimiting character marking the end of the
                string being parsed
&lt;chars&gt;         zero or more consecutive occurrences of the
                character char
&lt;space&gt;         a delimiting space character
&lt;spaces&gt;        zero or more consecutive occurrences of the
                character space
&lt;quote&gt;         a delimiting double quote
&lt;paren&gt;         a delimiting right parenthesis
&lt;eol&gt;           an implied delimiter marking the end of a line
ccc             a parsed sequence of arbitrary characters,
                excluding the delimiter character
name            a token delimited by space, equivalent to
                ccc&lt;space&gt; or ccc&lt;eol&gt;
</PRE>

<P>

<hr>
<A name=2.2.4>
<H3>2.2.4 Glossary notation</H3>
</a>

The glossary entries for each word set are listed in the standard ASCII
collating sequence.  Each glossary entry specifies an ANS Forth word and
consists of two parts: an index line and the semantic description of the
definition.

<P>

<hr>
<A name=2.2.4.1>
<H4>2.2.4.1 Glossary index line</H4>
</a>

The index line is a single-line entry containing, from left to right:
<P>

<UL>
<LI>Section number,
the last four digits of which assign a unique
sequential number to all words included in this Standard;
<LI>DEFINITION-NAME
in upper-case, mono-spaced, bold-face letters;
<LI>Natural-language
pronunciation in quotes if it differs from English;
<LI>Word-set
designator from table 2.2. The designation for extensions
word sets includes <B>EXT</B>.
</UL>

<P>

<a name=table.2.2>
Table 2.2 - Word set designators
</a>
<P>


<PRE>
Word set                        Designator
--------                        ----------
<a href=dpans6.htm>Core word set</a>                   CORE
<a href=dpans7.htm>Block word set</a>                  BLOCK
<a href=dpans8.htm>Double-Number word set</a>          DOUBLE
<a href=dpans9.htm>Exception word set</a>              EXCEPTION
<a href=dpans10.htm>Facility word set</a>               FACILITY
<a href=dpans11.htm>File-Access word set</a>            FILE
<a href=dpans12.htm>Floating-Point word set</a>         FLOATING
<a href=dpans13.htm>Locals word set</a>                 LOCALS
<a href=dpans14.htm>Memory-Allocation word set</a>      MEMORY
<a href=dpans15.htm>Programming-Tools word set</a>      TOOLS
<a href=dpans16.htm>Search-Order word set</a>           SEARCH
<a href=dpans17.htm>String-Handling word set</a>        STRING
</PRE>

<P>

<hr>
<A name=2.2.4.2>
<H4>2.2.4.2 Glossary semantic description</H4>
</a>

The first paragraph of the semantic description contains a stack notation for
each stack affected by execution of the word.  The remaining paragraphs
contain a text description of the semantics.  See 
<a href=dpans3.htm#3.4.3>3.4.3</a> Semantics.

<P>

<hr>
<A name=2.3>
<H2>2.3 References</H2>
</a>

The following national and international standards are referenced in this
Standard:

<P>

ANSI X3.172-1990, Dictionary for information systems 
(<a href=dpans2.htm#2.1>2.1</a> Definition of terms);

<P>

ANSI X3.4-1974, American Standard Code for Information Interchange
(ASCII) 
(<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> Graphic characters);

<P>

ISO 646-1983, ISO 7-bit coded characterset for information
interchange, International Reference Version (IRV) 
(<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> Graphic characters);

<P>

ANSI/IEEE 754-1985, Floating-point standard 
(<a href=dpans12.htm#12.2.1>12.2.1</a> Definition of terms).


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans3.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpans3.htm/     851247000   500   0     100644  48814     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans2.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans4.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=3.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>3. Usage requirements</H1>

A system shall provide all of the words defined in 
<a href=dpans6.htm#6.1>6.1</a> Core Words.  It
may also provide any words defined in the optional word sets and
extensions word sets.  No standard word provided by a system shall alter
the system state in a way that changes the effect of execution of any
other standard word except as provided in this Standard.  A system may
contain non-standard extensions, provided that they are consistent with
the requirements of this Standard.

<P>

The implementation of a system may use words and techniques outside the
scope of this Standard.

<P>

A system need not provide all words in executable form.  The
implementation may provide definitions, including definitions of words
in the Core word set, in source form only.  If so, the mechanism for
adding the definitions to the dictionary is implementation defined.

<P>

A program that requires a system to provide words or techniques not
defined in this Standard has an environmental dependency.

<P>
<code>
See:
<a href=dpansa3.htm#A.3>A.3</a> Usage requirements
</code>
<p>

<hr>
<A name=3.1>
<H2>3.1 Data types</H2>
</a>

A data type identifies the set of permissible values for a data object.
It is not a property of a particular storage location or position on a
stack.  Moving a data object shall not affect its type.

<P>

No data-type checking is required of a system.  An ambiguous condition
exists if an incorrectly typed data object is encountered.

<P>

<a href=dpans3.htm#table.3.1>Table 3.1</a> summarizes the data types used throughout this Standard.
Multiple instances of the same type in the description of a definition
are suffixed with a sequence digit subscript to distinguish them.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1>A.3.1</a> Date-types
</code>
<p>

<hr>
<A name=3.1.1>
<H3>3.1.1 Data-type relationships</H3>
</a>

Some of the data types are subtypes of other data types.  A data type i
is a subtype of type j if and only if the members of i are a subset of
the members of j.  The following list represents the subtype
relationships using the phrase <B>i =&gt; j</B> to denote <B>i is a subtype
of j</B>.  The subtype relationship is transitive; if i =&gt; j and j =&gt; k
then i =&gt; k:

<PRE>
	+n => u => x;
	+n => n => x;
	char => +n;
	a-addr => c-addr => addr => u;
	flag => x;
	xt => x;
	+d => d => xd;
	+d => ud => xd.
</PRE>
<P>

Any Forth definition that accepts an argument of type i shall also accept an
argument that is a subtype of i.

<P>

<hr>
<A name=3.1.2>
<H3>3.1.2 Character types</H3>
</a>

Characters shall be at least one address unit wide, contain at least eight
bits, and have a size less than or equal to cell size.

<P>

The characters provided by a system shall include the graphic characters
{32..126}, which represent graphic forms as shown in 
<a href=dpans3.htm#table.3.2>table 3.2</a>.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.2>A.3.1.2</a> Character types
</code>
<p>

<hr>
<A name=3.1.2.1>
<H2>3.1.2.1 Graphic characters</H2>
</a>

A graphic character is one that is normally displayed (e.g., A, #, &, 6).
These values and graphics, shown in 
<a href=dpans3.htm#table.3.2>table 3.2</a>, are taken directly from ANS
X3.4-1974 (ASCII) and ISO 646-1983, International Reference Version (IRV).
The graphic forms of characters outside the hex range {20..7E} are
implementation-defined.  Programs that use the graphic hex 24 (the currency
sign) have an environmental dependency.

<P>

The graphic representation of characters is not restricted to particular type
fonts or styles.  The graphics here are examples.

<P>

<hr>
<A name=3.1.2.2>
<H4>3.1.2.2 Control characters</H4>
</a>

All non-graphic characters included in the implementation-defined character
set are defined in this Standard as control characters.  In particular, the
characters {0..31}, which could be included in the implementation-defined
character set, are control characters.

<P>

Programs that require the ability to send or receive control characters have
an environmental dependency.

<P>

<hr>
<h3><a name=table.3.1>Table 3.1</a> - Data types</h3>
<P>


<PRE>
Symbol          Data type                         Size on stack
------          ---------                         -------------
flag            flag                              1 cell
true            true flag                         1 cell
false           false flag                        1 cell
char            character                         1 cell
n               signed number                     1 cell
+n              non-negative number               1 cell
u               unsigned number                   1 cell
n|u 1           number                            1 cell
x               unspecified cell                  1 cell
xt              execution token                   1 cell
addr            address                           1 cell
a-addr          aligned address                   1 cell
c-addr          character-aligned address         1 cell
d               double-cell signed number         2 cells
+d              double-cell non-negative number   2 cells
ud              double-cell unsigned number       2 cells
d|ud 2          double-cell number                2 cells
xd              unspecified cell pair             2 cells
colon-sys       definition compilation            implementation dependent
do-sys          do-loop structures                implementation dependent
case-sys        CASE structures                   implementation dependent
of-sys          OF structures                     implementation dependent
orig            control-flow origins              implementation dependent
dest            control-flow destinations         implementation dependent
loop-sys        loop-control parameters           implementation dependent
nest-sys        definition calls                  implementation dependent
i*x, j*x, k*x 3 any data type                     0 or more cells
</PRE>

<P>

<B>1</B> May be either a signed number or an unsigned number depending
on context.

<P>

<B>2</B> May be either a double-cell signed number or a double-cell
unsigned number depending on context.

<P>

<B>3</B> May be an undetermined number of stack entries of unspecified
type.  For examples of use, see 
<a href=dpans6.htm#6.1.1370>6.1.1370</a> EXECUTE, 
<a href=dpans6.htm#6.1.2050>6.1.2050</a> QUIT.

<p>
<code>
See:
<a href=dpans11.htm#11.3.1>11.3.1</a> Data types,
<a href=dpans12.htm#12.3.1>12.3.1</a> Data types,
<a href=dpans14.htm#14.3.1>14.3.1</a> Data types,
<a href=dpans16.htm#16.3.1>16.3.1</a> Data types.
</code>
<p>

<HR>
<h3><a name=table.3.2>Table 3.2</a> - Standard graphic characters</h3>


<PRE>
Hex     IRV     ASCII
---     ---     -----
20
21      !       !
22      "       "
23      #       #
24      °       $
25      %       %
26      &       &
27      '       '
28      (       (
29      )       )
2A      *       *
2B      +       +
2C      ,       ,
2D      -       -
2E      .       .
2F      /       /
30      0       0
31      1       1
32      2       2
33      3       3
34      4       4
35      5       5
36      6       6
37      7       7
38      8       8
39      9       9
3A      :       :
3B      ;       ;
3C      <       <
3D      =       =
3E      >       >
3F      ?       ?
40      @       @
41      A       A
42      B       B
43      C       C
44      D       D
45      E       E
46      F       F
47      G       G
48      H       H
49      I       I
4A      J       J
4B      K       K
4C      L       L
4D      M       M
4E      N       N
4F      O       O
50      P       P
51      Q       Q
52      R       R
53      S       S
54      T       T
55      U       U
56      V       V
57      W       W
58      X       X
59      Y       Y
5A      Z       Z
5B      [       [
5C      \       \
5D      ]       ]
5E      ^       ^
5F      _       _
60      `       `
61      a       a
62      b       b
63      c       c
64      d       d
65      e       e
66      f       f
67      g       g
68      h       h
69      i       i
6A      j       j
6B      k       k
6C      l       l
6D      m       m
6E      n       n
6F      o       o
70      p       p
71      q       q
72      r       r
73      s       s
74      t       t
75      u       u
76      v       v
77      w       w
78      x       x
79      y       y
7A      z       z
7B      {       {
7C      |       |
7D      }       }
7E      ~       ~
</PRE>

<P>

<hr>
<A name=3.1.3>
<H3>3.1.3 Single-cell types</H3>
</a>

The implementation-defined fixed size of a cell is specified in address units
and the corresponding number of bits.  See 
<a href=dpanse.htm#E.2>E.2</a> Hardware peculiarities.

<P>

Cells shall be at least one address unit wide and contain at least sixteen
bits.  The size of a cell shall be an integral multiple of the size of a
character.  Data-stack elements, return-stack elements, addresses, execution
tokens, flags, and integers are one cell wide.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3>A.3.1.3</a> Single-cell types
</code>
<p>

<hr>
<A name=3.1.3.1>
<H4>3.1.3.1 Flags</H4>
</a>

Flags may have one of two logical states, true or false.  Programs that use
flags as arithmetic operands have an environmental dependency.

<P>

A true flag returned by a standard word shall be a single-cell value with all
bits set.  A false flag returned by a standard word shall be a single-cell
value with all bits clear.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.1>A.3.1.3.1</a> Flags
</code>
<p>

<hr>
<A name=3.1.3.2>
<H4>3.1.3.2 Integers</H4>
</a>

The implementation-defined range of signed integers shall include
{-32767..+32767}.

<P>

The implementation-defined range of non-negative integers shall include
{0..32767}.

<P>

The implementation-defined range of unsigned integers shall include
{0..65535}.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.2>A.3.1.3.2</a> Integers
</code>
<p>

<hr>
<A name=3.1.3.3>
<H4>3.1.3.3 Addresses</H4>
</a>

An address identifies a location in data space with a size of one address
unit, which a program may fetch from or store into except for the restrictions
established in this Standard.  The size of an address unit is specified in
bits.  Each distinct address value identifies exactly one such storage
element.  See 
<a href=dpans3.htm#3.3.3>3.3.3</a> Data space.

<P>

The set of character-aligned addresses, addresses at which a character can be
accessed, is an implementation-defined subset of all addresses.  Adding the
size of a character to a character-aligned address shall produce another
character-aligned address.

<P>

The set of aligned addresses is an implementation-defined subset of
character-aligned addresses.  Adding the size of a cell to an aligned address
shall produce another aligned address.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.3>A.3.1.3.3</a> Addresses
</code>
<p>

<hr>
<A name=3.1.3.4>
<H4>3.1.3.4 Counted strings</H4>
</a>

A counted string in memory is identified by the address (c-addr) of its length
character.

<P>

The length character of a counted string shall contain a binary
representation of the number of data characters, between zero and the
implementation-defined maximum length for a counted string.  The maximum
length of a counted string shall be at least 255.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.4>A.3.1.3.4</a> Counted strings
</code>
<p>

<hr>
<A name=3.1.3.5>
<H4>3.1.3.5 Execution tokens</H4>
</a>

Different definitions may have the same execution token if the
definitions are equivalent.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.5>A.3.1.3.5</a> Execution tokens
</code>
<p>

<hr>
<A name=3.1.4>
<H3>3.1.4 Cell-pair types</H3>
</a>

A cell pair in memory consists of a sequence of two contiguous cells.  The
cell at the lower address is the first cell, and its address is used to
identify the cell pair.  Unless otherwise specified, a cell pair on a stack
consists of the first cell immediately above the second cell.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.4>A.3.1.4</a> Cell-pair types
</code>
<p>

<hr>
<A name=3.1.4.1>
<H4>3.1.4.1 Double-cell integers</H4>
</a>

On the stack, the cell containing the most significant part of a
double-cell integer shall be above the cell containing the least
significant part.

<P>

The implementation-defined range of double-cell signed integers shall
include {-2147483647..+2147483647}.

<P>

The implementation-defined range of double-cell non-negative integers
shall include {0..2147483647}.

<P>

The implementation-defined range of double-cell unsigned integers shall
include {0..4294967295}.  Placing the single-cell integer zero on the
stack above a single-cell unsigned integer produces a double-cell
unsigned integer with the same value.  See 
<a href=dpans3.htm#3.2.1.1>3.2.1.1</a> Internal number
representation.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.4.1>A.3.1.4.1</a> Double-cell integers
</code>
<p>

<hr>
<A name=3.1.4.2>
<H4>3.1.4.2 Character strings</H4>
</a>

A string is specified by a cell pair (c-addr u) representing its
starting address and length in characters.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.4>A.3.1.3.4</a> Counted strings
</code>
<p>

<hr>
<A name=3.1.5>
<H3>3.1.5 System types</H3>
</a>

The system data types specify permitted word combinations during
compilation and execution.

<P>

<hr>
<A name=3.1.5.1>
<H4>3.1.5.1 System-compilation types</H4>
</a>

These data types denote zero or more items on the control-flow stack
(see 
<a href=dpans3.htm#3.2.3.2>3.2.3.2</a>).  
The possible presence of such items on the data stack
means that any items already there shall be unavailable to a program
until the control-flow-stack items are consumed.

<P>

The implementation-dependent data generated upon beginning to compile a
definition and consumed at its close is represented by the symbol
colon-sys throughout this Standard.

<P>

The implementation-dependent data generated upon beginning to compile a
do-loop structure such as 
<a href=dpans6.htm#6.1.1240>DO</a> ... 
<a href=dpans6.htm#6.1.1800>LOOP</a> 
and consumed at its close is
represented by the symbol do-sys throughout this Standard.

<P>

The implementation-dependent data generated upon beginning to compile a
<a href=dpans6.htm#6.2.0873>CASE</a> ... 
<a href=dpans6.htm#6.2.1342>ENDCASE</a> 
structure and consumed at its close is represented by
the symbol case-sys throughout this Standard.

<P>

The implementation-dependent data generated upon beginning to compile an
<a href=dpans6.htm#6.2.1950>OF</a> ... 
<a href=dpans6.htm#6.2.1343>ENDOF</a> 
structure and consumed at its close is represented by the
symbol of-sys throughout this Standard.

<P>

The implementation-dependent data generated and consumed by executing
the other standard control-flow words is represented by the symbols orig
and dest throughout this Standard.

<P>

<hr>
<A name=3.1.5.2>
<H4>3.1.5.2 System-execution types</H4>
</a>

These data types denote zero or more items on the return stack.  Their
possible presence means that any items already on the return stack shall
be unavailable to a program until the system-execution items are
consumed.

<P>

The implementation-dependent data generated upon beginning to execute a
definition and consumed upon exiting it is represented by the symbol
nest-sys throughout this Standard.

<P>

The implementation-dependent loop-control parameters used to control the
execution of do-loops are represented by the symbol loop-sys throughout
this Standard.  Loop-control parameters shall be available inside the
do-loop for words that use or change these parameters, words such as 
<a href=dpans6.htm#6.1.1680>I</a>,
<a href=dpans6.htm#6.1.1730>J</a>, 
<a href=dpans6.htm#6.1.1760>LEAVE</a> and 
<a href=dpans6.htm#6.1.2380>UNLOOP</a>.

<P>

<hr>
<A name=3.2>
<H2>3.2 The implementation environment</H2>
</a>

<p>


<hr>
<A name=3.2.1>
<H3>3.2.1 Numbers</H3>
</a>

<p>
<code>
See:
<a href=dpansa3.htm#A.3.2.1>A.3.2.1</a> Numbers
</code>
<p>


<hr>
<A name=3.2.1.1>
<H4>3.2.1.1 Internal number representation</H4>
</a>

This Standard allows one's complement, two's complement, or
sign-magnitude number representations and arithmetic.  Arithmetic zero
is represented as the value of a single cell with all bits clear.
<P>

The representation of a number as a compiled literal or in memory is
implementation dependent.

<P>

<hr>
<A name=3.2.1.2>
<H4>3.2.1.2 Digit conversion</H4>
</a>

Numbers shall be represented externally by using characters from the
standard character set.

<P>

Conversion between the internal and external forms of a digit shall
behave as follows:

<P>

The value in 
<a href=dpans6.htm#6.1.0750>BASE</a> 
is the radix for number conversion.  A digit has a
value ranging from zero to one less than the contents of BASE.  The
digit with the value zero corresponds to the character <B>0</B>.  This
representation of digits proceeds through the character set to the
decimal value nine corresponding to the character <B>9</B>.  For digits
beginning with the decimal value ten the graphic characters beginning
with the character <B>A</B> are used.  This correspondence continues up
to and including the digit with the decimal value thirty-five which is
represented by the character <B>Z</B>.  The conversion of digits outside
this range is implementation defined.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.2.1.2>A.3.2.1.2</a> Digit conversion
</code>
<p>

<hr>
<A name=3.2.1.3>
<H4>3.2.1.3 Free-field number display</H4>
</a>

Free-field number display uses the characters described in digit
conversion, without leading zeros, in a field the exact size of the
converted string plus a trailing space.  If a number is zero, the least
significant digit is not considered a leading zero.  If the number is
negative, a leading minus sign is displayed.

<P>

Number display may use the pictured numeric output string buffer to hold
partially converted strings (see 
<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions).

<P>

<hr>
<A name=3.2.2>
<H3>3.2.2 Arithmetic</H3>
</a>

<p>


<hr>
<A name=3.2.2.1>
<H4>3.2.2.1 Integer division</H4>
</a>

Division produces a quotient q and a remainder r by dividing operand a
by operand b.  Division operations return q, r, or both.  The identity
b*q + r = a shall hold for all a and b.

<P>

When unsigned integers are divided and the remainder is not zero, q is
the largest integer less than the true quotient.

<P>

When signed integers are divided, the remainder is not zero, and a and b
have the same sign, q is the largest integer less than the true
quotient.  If only one operand is negative, whether q is rounded toward
negative infinity (floored division) or rounded towards zero (symmetric
division) is implementation defined.

<P>

Floored division is integer division in which the remainder carries the
sign of the divisor or is zero, and the quotient is rounded to its
arithmetic floor.  Symmetric division is integer division in which the
remainder carries the sign of the dividend or is zero and the quotient
is the mathematical quotient <B>rounded towards zero</B> or
<B>truncated</B>.  Examples of each are shown in tables 
<a href=dpans3.htm#table.3.3>3.3</a> and 
<a href=dpans3.htm#table.3.3>3.4</a>.

<P>

In cases where the operands differ in sign and the rounding direction
matters, a program shall either include code generating the desired form
of division, not relying on the implementation-defined default result,
or have an environmental dependency on the desired rounding direction.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.2.2.1>A.3.2.2.1</a> Integer division
</code>
<p>

<hr>
<h3><a name=table.3.3>Table 3.3</a> - Floored Division Example</h3>
<P>


<PRE>
Dividend        Divisor Remainder       Quotient
--------        ------- ---------       --------
10                 7       3                1
-10                7       4               -2
10                -7      -4               -2
-10               -7      -3                1
</PRE>
<P>


<hr>
<h3><a name=table.3.4>Table 3.4</a> - Symmetric Division Example</h3>


<PRE>
Dividend        Divisor Remainder       Quotient
--------        ------- ---------       --------
10                 7       3                1
-10                7      -3               -1
10                -7       3               -1
-10               -7      -3                1

</PRE>
<P>


<P>

<hr>
<A name=3.2.2.2>
<H4>3.2.2.2 Other integer operations</H4>
</a>

In all integer arithmetic operations, both overflow and underflow shall
be ignored.  The value returned when either overflow or underflow occurs
is implementation defined.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.2.2.2>A.3.2.2.2</a> Other integer operations
</code>
<p>

<hr>
<A name=3.2.3>
<H3>3.2.3 Stacks</H3>
</a>

<p>
<code>
See:
<a href=dpansa3.htm#A.3.2.3>A.3.2.3</a> Stacks
</code>
<p>

<hr>
<A name=3.2.3.1>
<H4>3.2.3.1 Data stack</H4>
</a>

Objects on the data stack
shall be one cell wide.

<P>

<hr>
<A name=3.2.3.2>
<H4>3.2.3.2 Control-flow stack</H4>
</a>

The control-flow stack is a last-in, first out list whose elements
define the permissible matchings of control-flow words and the
restrictions imposed on data-stack usage during the compilation of
control structures.

<P>

The elements of the control-flow stack are system-compilation data
types.

<P>

The control-flow stack may, but need not, physically exist in an
implementation.  If it does exist, it may be, but need not be,
implemented using the data stack.  The format of the control-flow stack
is implementation defined.  Since the control-flow stack may be
implemented using the data stack, items placed on the data stack are
unavailable to a program after items are placed on the control-flow
stack and remain unavailable until the control-flow stack items are
removed.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.2.3.2>A.3.2.3.2</a> Control-flow stack
</code>
<p>

<hr>
<A name=3.2.3.3>
<H4>3.2.3.3 Return stack</H4>
</a>

Items on the return stack shall consist of one or more cells.  A system
may use the return stack in an implementation-dependent manner during
the compilation of definitions, during the execution of do-loops, and
for storing run-time nesting information.

<P>

A program may use the return stack for temporary storage during the
execution of a definition subject to the following restrictions:

<UL>
<LI>A program shall not access values on the return stack (using 
<a href=dpans6.htm#6.1.2070>R@</a>,
<a href=dpans6.htm#6.1.2060>R&gt;</a>, 
<a href=dpans6.htm#6.2.0415>2R@</a> or 
<a href=dpans6.htm#6.2.0410>2R&gt;</a>) 
that it did not place there using 
<a href=dpans6.htm#6.1.0580>&gt;R</a> or 
<a href=dpans6.htm#6.2.0340>2&gt;R;</a>
<LI>A program shall not access from within a do-loop values placed
on the return stack before the loop was entered;
<LI>All values placed on the return stack within a do-loop shall be
removed before 
<a href=dpans6.htm#6.1.1680>I</a>, 
<a href=dpans6.htm#6.1.1730>J</a>, 
<a href=dpans6.htm#6.1.1800>LOOP</a>, 
<a href=dpans6.htm#6.1.0140>+LOOP</a>, 
<a href=dpans6.htm#6.1.2380>UNLOOP</a>, or 
<a href=dpans6.htm#6.1.1760>LEAVE</a> is executed;
<LI>All values placed on the return stack within a definition shall
be removed before the definition is terminated or before 
<a href=dpans6.htm#6.1.1380>EXIT</a> is
executed.
</UL>

<P>
<code>
See:
<a href=dpansa3.htm#A.3.2.3.3>A.3.2.3.3</a> Return stack
</code>
<p>

<hr>
<A name=3.2.4>
<H3>3.2.4 Operator terminal</H3>
</a>

<code>
See:
<a href=dpans1.htm#1.2.2>1.2.2</a> Exclusions
</code>
<P>

<hr>
<A name=3.2.4.1>
<H4>3.2.4.1 User input device</H4>
</a>

The method of selecting the user input
device is implementation defined.

<P>

The method of indicating the end of an input line of text is
implementation defined.

<P>

<hr>
<A name=3.2.4.2>
<H4>3.2.4.2 User output device</H4>
</a>

The method of selecting the user output device is implementation
defined.

<P>

<hr>
<A name=3.2.5>
<H3>3.2.5 Mass storage</H3>
</a>

A system need not provide any standard words for accessing mass storage.
If a system provides any standard word for accessing mass storage, it
shall also implement the Block word set.

<P>

<hr>
<A name=3.2.6>
<H3>3.2.6 Environmental queries</H3>
</a>

The name spaces for 
<a href=dpans6.htm#6.1.1345>ENVIRONMENT?</a> 
and definitions are disjoint.  Names of
definitions that are the same as ENVIRONMENT? strings shall not impair
the operation of ENVIRONMENT?.  
Table 3.5 contains the valid input
strings and corresponding returned value for inquiring about the
programming environment with ENVIRONMENT?.

<P>

<a name=table.3.5>
Table 3.5 - Environmental Query Strings
</a>
<P>



<PRE>
String                Value  Constant?       Meaning
                    data type
/COUNTED-STRING         n       yes     maximum size of a counted string,
                                        in characters
/HOLD                   n       yes     size of the pictured numeric output
                                        string buffer, in characters
/PAD                    n       yes     size of the scratch area pointed to
                                        by PAD, in characters
ADDRESS-UNIT-BITS       n       yes     size of one address unit, in bits
CORE                    flag    no      true if complete core word set
                                        present (i.e., not a subset as
                                        defined in <a href=dpans5.htm#5.1.1>5.1.1</a>)
CORE-EXT                flag    no      true if core extensions word
                                        set present
FLOORED                 flag    yes     true if floored division is the default
MAX-CHAR                u       yes     maximum value of any character in the
                                        implementation-defined character set
MAX-D                   d       yes     largest usable signed double number
MAX-N                   n       yes     largest usable signed integer
MAX-U                   u       yes     largest usable unsigned integer
MAX-UD                  ud      yes     largest usable unsigned double number
RETURN-STACK-CELLS      n       yes     maximum size of the return stack,
                                        in cells
STACK-CELLS             n       yes     maximum size of the data stack,
                                        in cells
</PRE>
<P>

If an environmental query (using ENVIRONMENT?) returns false (i.e.,
unknown) in response to a string, subsequent queries using the same
string may return true.  If a query returns true (i.e., known) in
response to a string, subsequent queries with the same string shall also
return true.  If a query designated as constant in the above table
returns true and a value in response to a string, subsequent queries
with the same string shall return true and the same value.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.2.6>A.3.2.6</a> Environmental queries,
<a href=dpans7.htm#7.3.1>7.3.1</a> Environmental queries,
<a href=dpans8.htm#8.3.1>8.3.1</a> Environmental queries,
<a href=dpans9.htm#9.3.4>9.3.4</a> Environmental queries,
<a href=dpans10.htm#10.3.2>10.3.2</a> Environmental queries,
<a href=dpans11.htm#11.3.3>11.3.3</a> Environmental queries,
<a href=dpans12.htm#12.3.4>12.3.4</a> Environmental queries,
<a href=dpans13.htm#13.3.2>13.3.2</a> Environmental queries,
<a href=dpans14.htm#14.3.2>14.3.2</a> Environmental queries,
<a href=dpans15.htm#15.3.1>15.3.1</a> Environmental queries,
<a href=dpans16.htm#16.3.2>16.3.2</a> Environmental queries,
<a href=dpans17.htm#17.3>17.3</a> Additional usage requirements.
</code>
<p>

<hr>
<A name=3.3>
<H2>3.3 The Forth dictionary</H2>
</a>

Forth words are organized into a structure called the dictionary.  While
the form of this structure is not specified by the Standard, it can be
described as consisting of three logical parts: a name space, a code
space, and a data space.  The logical separation of these parts does not
require their physical separation.

<P>

A program shall not fetch from or store into locations outside data
space.  An ambiguous condition exists if a program addresses name space
or code space.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.3>A.3.3</a> The Forth dictionary
</code>
<p>

<hr>
<A name=3.3.1>
<H3>3.3.1 Name space</H3>
</a>

The relationship between name space and data space is implementation
dependent.

<P>

<hr>
<A name=3.3.1.1>
<H4>3.3.1.1 Word lists</H4>
</a>

The structure of a word list is implementation dependent.  When
duplicate names exist in a word list, the latest-defined duplicate shall
be the one found during a search for the name.

<P>

<hr>
<A name=3.3.1.2>
<H4>3.3.1.2 Definition names</H4>
</a>

Definition names shall contain {1..31} characters.  A system may allow
or prohibit the creation of definition names containing non-standard
characters.

<P>

Programs that use lower case for standard definition names or depend on
the case-sensitivity properties of a system have an environmental
dependency.

<P>

A program shall not create definition names containing non-graphic
characters.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.3.1.2>A.3.3.1.2</a> Definition names
</code>
<p>

<hr>
<A name=3.3.2>
<H3>3.3.2 Code space</H3>
</a>

The relationship between code space and data space is implementation
dependent.

<P>

<hr>
<A name=3.3.3>
<H3>3.3.3 Data space</H3>
</a>

Data space is the only logical area of the dictionary for which standard
words are provided to allocate and access regions of memory.  These
regions are: contiguous regions, variables, text-literal regions, input
buffers, and other transient regions, each of which is described in the
following sections.  A program may read from or write into these regions
unless otherwise specified.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.3.3>A.3.3.3</a> Data space
</code>
<p>

<hr>
<A name=3.3.3.1>
<H4>3.3.3.1 Address alignment</H4>
</a>

Most addresses used in ANS Forth are aligned addresses (indicated by
a-addr) or character-aligned (indicated by c-addr).  
<a href=dpans6.htm#6.1.0706>ALIGNED</a>, 
<a href=dpans6.htm#6.1.0897>CHAR+</a>, and
arithmetic operations can alter the alignment state of an address on the
stack.  CHAR+ applied to an aligned address returns a character-aligned
address that can only be used to access characters.  Applying CHAR+ to a
character-aligned address produces the succeeding character-aligned
address.  Adding or subtracting an arbitrary number to an address can
produce an unaligned address that shall not be used to fetch or store
anything.  The only way to find the next aligned address is with
ALIGNED.  An ambiguous condition exists when 
<a href=dpans6.htm#6.1.0650>@</a>, 
<a href=dpans6.htm#6.1.0010>!</a>, , 
(<a href=dpans6.htm#6.1.0150>comma</a>), 
<a href=dpans6.htm#6.1.0130>+!</a>, 
<a href=dpans6.htm#6.1.0350>2@</a>, or
<a href=dpans6.htm#6.1.0310>2!</a> 
is used with an address that is not aligned, or when 
<a href=dpans6.htm#6.1.0870>C@</a>, 
<a href=dpans6.htm#6.1.0850>C!</a>, or 
<a href=dpans6.htm#6.1.0860>C,</a> is
used with an address that is not character-aligned.

<P>

The definitions of 
<a href=dpans6.htm#6.1.1000>6.1.1000</a> CREATE and 
<a href=dpans6.htm#6.1.2410>6.1.2410</a> VARIABLE require that
the definitions created by them return aligned addresses.

<P>

After definitions are compiled or the word 
<a href=dpans6.htm#6.1.0705>ALIGN</a> 
is executed the
data-space pointer is guaranteed to be aligned.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.3.3.1>A.3.3.3.1</a> Address alignment
</code>
<p>

<hr>
<A name=3.3.3.2>
<H4>3.3.3.2 Contiguous regions</H4>
</a>

A system guarantees that a region of data space allocated using 
<a href=dpans6.htm#6.1.0710>ALLOT</a>, ,
(<a href=dpans6.htm#6.1.0150>comma)</a>, C, 
(<a href=dpans6.htm#6.1.0860>c-comma</a>), and 
<a href=dpans6.htm#6.1.0705>ALIGN</a> 
shall be contiguous with the last
region allocated with one of the above words, unless the restrictions in
the following paragraphs apply.  The data-space pointer 
<a href=dpans6.htm#6.1.1650>HERE</a> 
always
identifies the beginning of the next data-space region to be allocated.
As successive allocations are made, the data-space pointer increases.  A
program may perform address arithmetic within contiguously allocated
regions.  The last region of data space allocated using the above
operators may be released by allocating a corresponding negatively-sized
region using ALLOT, subject to the restrictions of the following
paragraphs.

<P>

<a href=dpans6.htm#6.1.1000>CREATE</a> 
establishes the beginning of a contiguous region of data space,
whose starting address is returned by the CREATEd definition.  This
region is terminated by compiling the next definition.

<P>

Since an implementation is free to allocate data space for use by code,
the above operators need not produce contiguous regions of data space if
definitions are added to or removed from the dictionary between
allocations.  An ambiguous condition exists if deallocated memory
contains definitions.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.3.3.2>A.3.3.3.2</a> Contiguous regions
</code>
<p>

<hr>
<A name=3.3.3.3>
<H4>3.3.3.3 Variables</H4>
</a>

The region allocated for a variable may be non-contiguous with regions
subsequently allocated with , 
(<a href=dpans6.htm#6.1.0150>comma</a>) or 
<a href=dpans6.htm#6.1.0710>ALLOT</a>.  
For example, in:


<PRE>
        VARIABLE X  1 CELLS ALLOT
</PRE>
<P>

the region X and the region
ALLOTted could be non-contiguous.

<P>

Some system-provided variables, such as 
<a href=dpans6.htm#6.1.2250>STATE</a>, 
are restricted to read-only
access.

<P>

<hr>
<A name=3.3.3.4>
<H4>3.3.3.4 Text-literal regions</H4>
</a>

The text-literal regions, specified by strings compiled with 
<a href=dpans6.htm#6.1.2165>S"</a> and 
<a href=dpans6.htm#6.2.0855>C"</a>,
may be read-only.

<P>

A program shall not store into the text-literal regions created by S"
and C" nor into any read-only system variable or read-only transient
regions.  An ambiguous condition exists when a program attempts to store
into read-only regions.

<P>

<hr>
<A name=3.3.3.5>
<H4>3.3.3.5 Input buffers</H4>
</a>

The address, length, and content of the input buffer may be transient.
A program shall not write into the input buffer.  In the absence of any
optional word sets providing alternative input sources, the input buffer
is either the terminal-input buffer, used by 
<a href=dpans6.htm#6.1.2050>QUIT</a> to hold one line from
the user input device, or a buffer specified by 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>.  In all cases,
<a href=dpans6.htm#6.1.2216>SOURCE</a> returns the beginning 
address and length in characters of the
current input buffer.

<P>

The minimum size of the terminal-input
buffer shall be 80 characters.

<P>

The address and length returned by SOURCE, the string returned by 
<a href=dpans6.htm#6.2.2008>PARSE</a>,
and directly computed input-buffer addresses are valid only until the
text interpreter does I/O to refill the input buffer or the input source
is changed.

<P>

A program may modify the size of the parse area by changing the contents
of 
<a href=dpans6.htm#6.1.0560>&gt;IN</a> 
within the limits imposed by this Standard.  For example, if the
contents of &gt;IN are saved before a parsing operation and restored
afterwards, the text that was parsed will be available again for
subsequent parsing operations.  The extent of permissible repositioning
using this method depends on the input 
source (see <a href=dpans7.htm#7.3.3>7.3.3</a> Block buffer
regions and <a href=dpans11.htm#11.3.4>11.3.4</a> Input source).

<P>

A program may directly examine the input buffer using its address and
length as returned by SOURCE; the beginning of the parse area within the
input buffer is indexed by the number in >IN.  The values are valid for
a limited time.  An ambiguous condition exists if a program modifies the
contents of the input buffer.

<p>
<code>
See:
<a href=a0006.htm>RFI 0006</a> Writing to Input Buffers
</code>
<p>

<hr>
<A name=3.3.3.6>
<H4>3.3.3.6 Other transient regions</H4>
</a>

The data space regions identified by 
<a href=dpans6.htm#6.2.2000>PAD</a>, 
<a href=dpans6.htm#6.1.2450>WORD</a>, and 
<a href=dpans6.htm#6.1.0040>#&gt;</a> 
(the pictured
numeric output string buffer) may be transient.  Their addresses and
contents may become invalid after:

<UL>
<LI>a definition is created via a defining word;
<LI>definitions are compiled with 
: or 
:NONAME;
<LI>data space is allocated using 
<a href=dpans6.htm#6.1.0710>ALLOT</a>, , 
(<a href=dpans6.htm#6.1.0150>comma</a>),
C, 
(<a href=dpans6.htm#6.1.0860>c-comma</a>), or 
<a href=dpans6.htm#6.1.0705>ALIGN</a>.
</UL>
<P>

The previous contents of the regions identified by WORD and #&gt; may be
invalid after each use of these words.  Further, the regions returned by
WORD and #&gt; may overlap in memory.  Consequently, use of one of these
words can corrupt a region returned earlier by a different word.  The
other words that construct pictured numeric output strings 
(<a href=dpans6.htm#6.1.0490>&lt;#</a>, 
<a href=dpans6.htm#6.1.0030>#</a>, 
<a href=dpans6.htm#6.1.0050>#S</a>,
and 
<a href=dpans6.htm#6.1.1670>HOLD</a>) 
may also modify the contents of these regions.  Words that
display numbers may be implemented using pictured numeric output words.
Consequently, .  
(<a href=dpans6.htm#6.1.0180>dot</a>), 
<a href=dpans6.htm#6.2.0210>.R</a>, 
<a href=dpans15.htm#15.6.1.0220>.S</a>, 
<a href=dpans15.htm#15.6.1.0600>?</a>, 
<a href=dpans8.htm#8.6.1.1060>D.</a>, 
<a href=dpans8.htm#8.6.1.1070>D.R</a>, 
<a href=dpans6.htm#6.1.2320>U.</a>, and 
<a href=dpans6.htm#6.2.2330>U.R</a> 
could also
corrupt the regions.

<P>

The size of the scratch area whose address is returned by PAD shall be
at least 84 characters.  The contents of the region addressed by PAD are
intended to be under the complete control of the user: no words defined
in this Standard place anything in the region, although changing
data-space allocations as described in 
<a href=dpans3.htm#3.3.3.2>3.3.3.2</a> Contiguous regions may
change the address returned by PAD.  Non-standard words provided by an
implementation may use PAD, but such use shall be documented.

<P>

The size of the region identified by WORD shall be at least 33
characters.

<P>

The size of the pictured numeric output string buffer shall be at least
(2*n) + 2 characters, where n is the number of bits in a cell.  Programs
that consider it a fixed area with unchanging access parameters have an
environmental dependency.

<p>
<code>
See:
<a href=dpansa3.htm#A.3.3.3.6>A.3.3.3.6</a> Other transient regions,
<a href=dpans11.htm#11.3.5>11.3.5</a> Other transient regions.
</code>
<p>

<hr>
<a name=3.4>
<H2>3.4 The Forth text interpreter</H2>
</a>

Upon start-up, a system shall be able to interpret, as described by
<a href=dpans6.htm#6.1.2050>6.1.2050</a> QUIT, Forth source code 
received interactively from a user
input device.

<P>

Such interactive systems usually furnish a <B>prompt</B> indicating that
they have accepted a user request and acted on it.  The
implementation-defined Forth prompt should contain the word <B>OK</B> in
some combination of upper or lower case.

<P>

Text interpretation (see 
<a href=dpans6.htm#6.1.1360>6.1.1360</a> EVALUATE and 
<a href=dpans6.htm#6.1.2050>6.1.2050</a> QUIT) shall
repeat the following steps until either the parse area is empty or an
ambiguous condition exists:

<p>
a) Skip leading spaces and parse a name (see 
<a href=dpans3.htm#3.4.1>3.4.1</a>);
<p>
b) Search the dictionary name space (see 
<a href=dpans3.htm#3.4.2>3.4.2</a>). If a definition name
matching the string is found:
<OL>
<LI>if interpreting, perform the interpretation semantics of the
definition (see 
<a href=dpans3.htm#3.4.3.2>3.4.3.2</a>), and continue at a);
<LI>if compiling, perform the compilation semantics of the definition (see
<a href=dpans3.htm#3.4.3.3>3.4.3.3</a>), and continue at a).
</ol>
<p>
c) If a definition name matching the string is not found, attempt to
convert the string to a number (see 
<a href=dpans3.htm#3.4.1.3>3.4.1.3</a>). If successful:
<ol>
<LI>if interpreting, place the number on the data stack, and continue at a);
<LI>if compiling, compile code that when executed will place the number on
the stack (see 
<a href=dpans6.htm#6.1.1780>6.1.1780</a> LITERAL), and continue at a);
</ol>
<p>
d) If unsuccessful, an ambiguous condition exists (see 
<a href=dpans3.htm#3.4.4>3.4.4</a>).

<P>


<hr>
<A name=3.4.1>
<H3>3.4.1 Parsing</H3>
</a>

Unless otherwise noted, the number of characters parsed may be from zero
to the implementation-defined maximum length of a counted string.

<P>

If the parse area is empty, i.e., when the number in 
<a href=dpans6.htm#6.1.0560>&gt;IN</a> 
is equal to the
length of the input buffer, or contains no characters other than
delimiters, the selected string is empty.  Otherwise, the selected
string begins with the next character in the parse area, which is the
character indexed by the contents of &gt;IN.  An ambiguous condition exists
if the number in &gt;IN is greater than the size of the input buffer.

<P>

If delimiter characters are present in the parse area after the
beginning of the selected string, the string continues up to and
including the character just before the first such delimiter, and the
number in &gt;IN is changed to index immediately past that delimiter, thus
removing the parsed characters and the delimiter from the parse area.
Otherwise, the string continues up to and including the last character
in the parse area, and the number in &gt;IN is changed to the length of the
input buffer, thus emptying the parse area.

<P>

Parsing may change the contents of &gt;IN, but shall not affect the
contents of the input buffer.  Specifically, if the value in &gt;IN is
saved before starting the parse, resetting &gt;IN to that value immediately
after the parse shall restore the parse area without loss of data.

<P>

<hr>
<A name=3.4.1.1>
<H4>3.4.1.1 Delimiters</H4>
</a>

If the delimiter is the space character, hex 20 
(<a href=dpans6.htm#6.1.0770>BL</a>), 
control characters
may be treated as delimiters.  The set of conditions, if any, under
which a <B>space</B> delimiter matches control characters is
implementation defined.

<P>

To skip leading delimiters is to pass by zero or more contiguous
delimiters in the parse area before parsing.

<P>

<hr>
<A name=3.4.1.2>
<H4>3.4.1.2 Syntax</H4>
</a>

Forth has a simple, operator-ordered syntax.  The phrase A B C returns
values as if A were executed first, then B and finally C.  Words that
cause deviations from this linear flow of control are called
control-flow words.  Combinations of control-flow words whose stack
effects are compatible form control-flow structures.  Examples of
typical use are given for each control-flow word in
<A href=dpansa1.htm>Annex A</A>.

<P>

Forth syntax is extensible; for example, new control-flow words can be
defined in terms of existing ones.

<P>

This Standard does not require a
syntax or program-construct checker.

<P>

<hr>
<A name=3.4.1.3>
<H4>3.4.1.3 Text interpreter input number conversion</H4>
</a>

When converting input numbers, the text interpreter shall recognize both
positive and negative numbers, with a negative number represented by a
single minus sign, the character <B>-</B>, preceding the digits.  The
value in 
<a href=dpans6.htm#6.1.0750>BASE</a> 
is the radix for number conversion.

<P>

<hr>
<A name=3.4.2>
<H3>3.4.2 Finding definition names</H3>
</a>

A string matches a definition name if each character in the string
matches the corresponding character in the string used as the definition
name when the definition was created.  The case sensitivity (whether or
not the upper-case letters match the lower-case letters) is
implementation defined.  A system may be either case sensitive, treating
upper- and lower-case letters as different and not matching, or case
insensitive, ignoring differences in case while searching.

<P>

The matching of upper- and lower-case letters with alphabetic characters
in character set extensions such as accented international characters is
implementation defined.

<P>

A system shall be capable of finding the definition names defined by
this Standard when they are spelled with upper-case letters.

<P>

<hr>
<A name=3.4.3>
<H3>3.4.3 Semantics</H3>
</a>

The semantics of a Forth definition are implemented by machine code or a
sequence of execution tokens or other representations.  They are largely
specified by the stack notation in the glossary entries, which shows
what values shall be consumed and produced.  The prose in each glossary
entry further specifies the definition's behavior.

<P>

Each Forth definition may have several behaviors, described in the
following sections.  The terms <B>initiation semantics</B> and
<B>run-time semantics</B> refer to definition fragments, and have
meaning only within the individual glossary entries where they appear.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.4.3>A.3.4.3</a> Semantics,
<a href=a0005.htm>RFI 0005</a>.
</code>
<p>

<hr>
<A name=3.4.3.1>
<H4>3.4.3.1 Execution semantics</H4>
</a>

The execution semantics of each Forth definition are specified in an
<B>Execution:</B> section of its glossary entry.  When a definition has
only one specified behavior, the label is omitted.

<P>

Execution may occur implicitly, when the definition into which it has
been compiled is executed, or explicitly, when its execution token is
passed to 
<a href=dpans6.htm#6.1.1370>EXECUTE</a>.  
The execution semantics of a syntactically correct
definition under conditions other than those specified in this Standard
are implementation dependent.

<P>

Glossary entries for defining words include the execution semantics for
the new definition in a <i>name</i> <b>Execution:</B> section.

<P>

<hr>
<A name=3.4.3.2>
<H4>3.4.3.2 Interpretation semantics</H4>
</a>

Unless otherwise specified in an <B>Interpretation:</B> section of the
glossary entry, the interpretation semantics of a Forth definition are
its execution semantics.

<P>

A system shall be capable of executing, in interpretation state, all of
the definitions from the Core word set and any definitions included from
the optional word sets or word set extensions whose interpretation
semantics are defined by this Standard.

<P>

A system shall be capable of executing, in interpretation state, any new
definitions created in accordance with 
<a href=dpans3.htm#3.>3.</a>  Usage requirements.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.4.3.2>A.3.4.3.2</a> Interpretation semantics
</code>
<p>

<hr>
<A name=3.4.3.3>
<H4>3.4.3.3 Compilation semantics</H4>
</a>

Unless otherwise specified in a <B>Compilation:</B> section of the
glossary entry, the compilation semantics of a Forth definition shall be
to append its execution semantics to the execution semantics of the
current definition.

<P>
<code>
See:
<a href=a0007.htm>RFI 0007</a> Distinction between <em>immediacy</em> and <em>special compilation semantics</em>.
</code>
<p>

<hr>
<A name=3.4.4>
<H3>3.4.4 Possible actions on an ambiguous condition</H3>
</a>

When an ambiguous condition exists, a system may take one or more of the
following actions:

<UL>
<LI>ignore and continue;
<LI>display a message;
<LI>execute a particular word;
<LI>set interpretation state and begin text interpretation;
<LI>take other implementation-defined actions;
<LI>take implementation-dependent actions.
</UL>
<P>

The response to a particular ambiguous condition need not be the same
under all circumstances.

<P>

<hr>
<A name=3.4.5>
<H3>3.4.5 Compilation</H3>
</a>

A program shall not attempt to
nest compilation of definitions.

<P>

During the compilation of the current definition, a program shall not
execute any defining word, 
<a href=dpans6.htm#6.2.0455>:NONAME</a>, 
or any definition that allocates
dictionary data space.  The compilation of the current definition may be
suspended using [ 
(<a href=dpans6.htm#6.1.2500>left-bracket</a>) 
and resumed using ] 
(<a href=dpans6.htm#6.1.2540>right-bracket</a>).
While the compilation of the current definition is suspended, a program
shall not execute any defining word, :NONAME, or any definition that
allocates dictionary data space.

<p>
<code>
See:
<a href=dpansa3.htm#A.3.4.5>A.3.4.5</a> Compilation
</code>
<p>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans4.htm><IMG   src="right.gif" ></A>  Next Section
<P>
</BODY>
</HTML>
dpans4.htm/     845512860   500   0     100644  13556     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans3.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans5.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=4.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>4. Documentation requirements</H1>

When it is impossible or infeasible for a system or program to define a
particular behavior itself, it is permissible to state that the behavior
is unspecifiable and to explain the circumstances and reasons why this is so.

<P>

<hr>
<A name=4.1>
<H2>4.1 System documentation</H2>
</a>


<hr>
<A name=4.1.1>
<H3>4.1.1 Implementation-defined options</H3>
</a>

The implementation-defined items in the following list represent
characteristics and choices left to the discretion of the implementor,
provided that the requirements of this Standard are met.  A system shall
document the values for, or behaviors of, each item.

<UL>
<LI>aligned address requirements 
(<a href=dpans3.htm#3.1.3.3>3.1.3.3</a> Addresses);
<LI>behavior of 
<a href=dpans6.htm#6.1.1320>6.1.1320</a> EMIT for non-graphic characters;
<LI>character editing of 
<a href=dpans6.htm#6.1.0695>6.1.0695</a> ACCEPT and 
<a href=dpans6.htm#6.2.1390>6.2.1390</a> EXPECT;
<LI>character set 
(<a href=dpans3.htm#3.1.2>3.1.2</a> Character types, 
<a href=dpans6.htm#6.1.1320>6.1.1320</a> EMIT, 
<a href=dpans6.htm#6.1.1750>6.1.1750</a> KEY);
<LI>character-aligned address requirements 
(<a href=dpans3.htm#3.1.3.3>3.1.3.3</a> Addresses);
<LI>character-set-extensions matching characteristics 
(<a href=dpans3.htm#3.4.2>3.4.2</a> Finding
definition names);
<LI>conditions under which control characters match a space delimiter 
(<a href=dpans3.htm#3.4.1.1>3.4.1.1</a> Delimiters);
<LI>format of the control-flow stack 
(<a href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control-flow stack);
<LI>conversion of digits larger than thirty-five 
(<a href=dpans3.htm#3.2.1.2>3.2.1.2</a> Digit
conversion);
<LI>display after input terminates in 
<a href=dpans6.htm#6.1.0695>6.1.0695</a> ACCEPT and 
<a href=dpans6.htm#6.2.1390>6.2.1390</a> EXPECT;
<LI>exception abort sequence (as in 
<a href=dpans6.htm#6.1.0680>6.1.0680</a> ABORT");
<LI>input line terminator 
(<a href=dpans3.htm#3.2.4.1>3.2.4.1</a> User input device);
<LI>maximum size of a counted string, in characters 
(<a href=dpans3.htm#3.1.3.4>3.1.3.4</a> Counted
strings, 
<a href=dpans6.htm#6.1.2450>6.1.2450</a> WORD);
<LI>maximum size of a parsed string 
(<a href=dpans3.htm#3.4.1>3.4.1</a> Parsing);
<LI>maximum size of a definition name, in characters 
(<a href=dpans3.htm#3.3.1.2>3.3.1.2</a> Definition
names);
<LI>maximum string length for 
<a href=dpans6.htm#6.1.1345>6.1.1345</a> ENVIRONMENT?, in characters;
<LI>method of selecting 
<a href=dpans3.htm#3.2.4.1>3.2.4.1</a> User input device;
<LI>method of selecting 
<a href=dpans3.htm#3.2.4.2>3.2.4.2</a> User output device;
<LI>methods of dictionary compilation 
(<a href=dpans3.htm#3.3>3.3</a> The Forth dictionary);
<LI>number of bits in one address unit 
(<a href=dpans3.htm#3.1.3.3>3.1.3.3</a> Addresses);
<LI>number representation and arithmetic 
(<a href=dpans3.htm#3.2.1.1>3.2.1.1</a> Internal number
representation);
<LI>ranges for n, +n, u, d, +d, and ud 
(<a href=dpans3.htm#3.1.3>3.1.3</a> Single-cell types, 
<a href=dpans3.htm#3.1.4>3.1.4</a> Cell-pair types);
<LI>read-only data-space regions 
(<a href=dpans3.htm#3.3.3>3.3.3</a> Data space);
<LI>size of buffer at 
<a href=dpans6.htm#6.1.2450>6.1.2450</a> WORD 
(<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions);
<LI>size of one cell in address units 
(<a href=dpans3.htm#3.1.3>3.1.3</a> Single-cell types);
<LI>size of one character in address units 
(<a href=dpans3.htm#3.1.2>3.1.2</a> Character types);
<LI>size of the keyboard terminal input buffer 
(<a href=dpans3.htm#3.3.3.5>3.3.3.5</a> Input buffers);
<LI>size of the pictured numeric output string buffer 
(<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other
transient regions);
<LI>size of the scratch area whose address is returned by 
<a href=dpans6.htm#6.2.2000>6.2.2000</a> PAD 
(<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions);
<LI>system case-sensitivity characteristics 
(<a href=dpans3.htm#3.4.2>3.4.2</a> Finding definition
names);
<LI>system prompt 
(<a href=dpans3.htm#3.4>3.4</a> The Forth text interpreter, 
<a href=dpans6.htm#6.1.2050>6.1.2050</a> QUIT);
<LI>type of division rounding 
(<a href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division, 
<a href=dpans6.htm#6.1.0100>6.1.0100</a> */,
<a href=dpans6.htm#6.1.0110>6.1.0110</a> */MOD, 
<a href=dpans6.htm#6.1.0230>6.1.0230</a> /, 
<a href=dpans6.htm#6.1.0240>6.1.0240</a> /MOD, 
<a href=dpans6.htm#6.1.1890>6.1.1890</a> MOD);
<LI>values of 
<a href=dpans6.htm#6.1.2250>6.1.2250</a> STATE when true;
<LI>values returned after arithmetic overflow 
(<a href=dpans3.htm#3.2.2.2>3.2.2.2</a> Other integer
operations);
<LI>whether the current definition can be found after 
<a href=dpans6.htm#6.1.1250>6.1.1250</a> DOES&gt; 
(<a href=dpans6.htm#6.1.0450>6.1.0450</a> :).
</UL>

<P>

<hr>
<A name=4.1.2>
<H3>4.1.2 Ambiguous conditions</H3>
</a>

A system shall document the system action taken upon each of the general or
specific ambiguous conditions identified in this Standard.  See 
<a href=dpans3.htm#3.4.4>3.4.4</a> Possible
actions on an ambiguous condition.

<P>

The following general ambiguous conditions could occur because of a
combination of factors:

<UL>
<LI>a name is neither a valid definition name nor a valid number during
text interpretation 
(<a href=dpans3.htm#3.4>3.4</a> The Forth text interpreter);
<LI>a definition name exceeded the maximum length allowed 
(<a href=dpans3.htm#3.3.1.2>3.3.1.2</a>
Definition names);
<LI>addressing a region not listed in 
<a href=dpans3.htm#3.3.3>3.3.3</a> Data Space;
<LI>argument type incompatible with specified input parameter, e.g.,
passing a flag to a word expecting an n 
(<a href=dpans3.htm#3.1>3.1</a> Data types);
<LI>attempting to obtain the execution token, (e.g., with 
<a href=dpans6.htm#6.1.0070>6.1.0070</a> ',
<a href=dpans6.htm#6.1.1550>6.1.1550</a> FIND, 
etc.) of a definition with undefined interpretation semantics;
<LI>dividing by zero 
(<a href=dpans6.htm#6.1.0100>6.1.0100</a> */, 
<a href=dpans6.htm#6.1.0110>6.1.0110</a> */MOD, 
<a href=dpans6.htm#6.1.0230>6.1.0230</a> /, 
<a href=dpans6.htm#6.1.0240>6.1.0240</a> /MOD, 
<a href=dpans6.htm#6.1.1561>6.1.1561</a> FM/MOD, 
<a href=dpans6.htm#6.1.1890>6.1.1890</a> MOD, 
<a href=dpans6.htm#6.1.2214>6.1.2214</a> SM/REM, 
<a href=dpans6.htm#6.1.2370>6.1.2370</a> UM/MOD,
<a href=dpans8.htm#8.6.1.1820>8.6.1.1820</a> M*/);
<LI>insufficient data-stack space or return-stack space (stack overflow);
<LI>insufficient space for loop-control parameters;
<LI>insufficient space in the dictionary;
<LI>interpretating a word with undefined interpretation semantics;
<LI>modifying the contents of the input buffer or a string literal 
(<a href=dpans3.htm#3.3.3.4>3.3.3.4</a> Text-literal regions, 
<a href=dpans3.htm#3.3.3.5>3.3.3.5</a> Input buffers);
<LI>overflow of a pictured numeric output string;
<LI>parsed string overflow;
<LI>producing a result out of range, e.g., multiplication (using *)
results in a value too big to be represented by a single-cell integer 
(<a href=dpans6.htm#6.1.0090>6.1.0090</a> *, 
<a href=dpans6.htm#6.1.0100>6.1.0100</a> */, 
<a href=dpans6.htm#6.1.0110>6.1.0110</a> */MOD, 
<a href=dpans6.htm#6.1.0570>6.1.0570</a> &gt;NUMBER, 
<a href=dpans6.htm#6.1.1561>6.1.1561</a> FM/MOD,
<a href=dpans6.htm#6.1.2214>6.1.2214</a> SM/REM, 
<a href=dpans6.htm#6.1.2370>6.1.2370</a> UM/MOD, 
<a href=dpans6.htm#6.2.0970>6.2.0970</a> CONVERT, 
<a href=dpans8.htm#8.6.1.1820>8.6.1.1820</a> M*/);
<LI>reading from an empty data stack or return stack (stack underflow);
<LI>unexpected end of input buffer, resulting in an attempt to use a
zero-length string as a name;
</UL>
<P>

The following specific ambiguous conditions are noted in the glossary entries
of the relevant words:

<UL>
<LI>
<a href=dpans6.htm#6.1.0560>&gt;IN</a> 
greater than size of input buffer 
(<a href=dpans3.htm#3.4.1>3.4.1</a> Parsing);
<LI>
<a href=dpans6.htm#6.1.2120>6.1.2120</a> RECURSE appears after 
<a href=dpans6.htm#6.1.1250>6.1.1250</a> DOES&gt;;
<LI>argument input source different than current input source for 
<a href=dpans6.htm#6.2.2148>6.2.2148</a> RESTORE-INPUT;
<LI>data space containing definitions is de-allocated 
(<a href=dpans3.htm#3.3.3.2>3.3.3.2</a> Contiguous regions);
<LI>data space read/write with incorrect alignment 
(<a href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment);
<LI>data-space pointer not properly aligned 
(<a href=dpans6.htm#6.1.0150>6.1.0150</a> ,, 
<a href=dpans6.htm#6.1.0860>6.1.0860</a> C,);
<LI>less than u+2 stack items 
(<a href=dpans6.htm#6.2.2030>6.2.2030</a> PICK, 
<a href=dpans6.htm#6.2.2150>6.2.2150</a> ROLL);
<LI>loop-control parameters not available (
<a href=dpans6.htm#6.1.0140>6.1.0140</a> +LOOP, 
<a href=dpans6.htm#6.1.1680>6.1.1680</a> I,
<a href=dpans6.htm#6.1.1730>6.1.1730</a> J, 
<a href=dpans6.htm#6.1.1760>6.1.1760</a> LEAVE, 
<a href=dpans6.htm#6.1.1800>6.1.1800</a> LOOP, 
<a href=dpans6.htm#6.1.2380>6.1.2380</a> UNLOOP);
<LI>most recent definition does not have a name 
(<a href=dpans6.htm#6.1.1710>6.1.1710</a> IMMEDIATE);
<LI>name not defined by 
<a href=dpans6.htm#6.2.2405>6.2.2405</a> VALUE used by 
<a href=dpans6.htm#6.2.2295>6.2.2295</a> TO;
<LI>name not found 
(<a href=dpans6.htm#6.1.0070>6.1.0070</a> ', 
<a href=dpans6.htm#6.1.2033>6.1.2033</a> POSTPONE, 
<a href=dpans6.htm#6.1.2510>6.1.2510</a> ['], 
<a href=dpans6.htm#6.2.2530>6.2.2530</a> [COMPILE]);
<LI>parameters are not of the same type 
(<a href=dpans6.htm#6.1.1240>6.1.1240</a> DO, 
<a href=dpans6.htm#6.2.0620>6.2.0620</a> ?DO,
<a href=dpans6.htm#6.2.2440>6.2.2440</a> WITHIN);
<LI>
<a href=dpans6.htm#6.1.2033>6.1.2033</a> POSTPONE or 
<a href=dpans6.htm#6.2.2530>6.2.2530</a> [COMPILE] applied to 
<a href=dpans6.htm#6.2.2295>6.2.2295</a> TO;
<LI>string longer than a counted string returned by 
<a href=dpans6.htm#6.1.2450>6.1.2450</a> WORD;
<LI>u greater than or equal to the number of bits in a cell 
(<a href=dpans6.htm#6.1.1805>6.1.1805</a> LSHIFT, 
<a href=dpans6.htm#6.1.2162>6.1.2162</a> RSHIFT);
<LI>word not defined via 
<a href=dpans6.htm#6.1.1000>6.1.1000</a> CREATE 
(<a href=dpans6.htm#6.1.0550>6.1.0550</a> &gt;BODY, 
<a href=dpans6.htm#6.1.1250>6.1.1250</a> DOES&gt;);
<LI>words improperly used outside 
<a href=dpans6.htm#6.1.0490>6.1.0490</a> &lt;# and 
<a href=dpans6.htm#6.1.0040>6.1.0040</a> #&gt; 
(<a href=dpans6.htm#6.1.0030>6.1.0030</a> #,
<a href=dpans6.htm#6.1.0050>6.1.0050</a> #S, 
<a href=dpans6.htm#6.1.1670>6.1.1670</a> HOLD, 
<a href=dpans6.htm#6.1.2210>6.1.2210</a> SIGN).
</UL>

<P>

<hr>
<A name=4.1.3>
<H3>4.1.3 Other system documentation</H3>
</a>

A system shall provide the following information:
<P>

<UL>
<LI>list of non-standard words using 
<a href=dpans6.htm#6.2.2000>6.2.2000</a> PAD 
(<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient
regions);
<LI>operator's terminal facilities available;
<LI>program data space available, in address units;
<LI>return stack space available, in cells;
<LI>stack space available, in cells;
<LI>system dictionary space required, in address units.
</UL>

<P>

<hr>
<A name=4.2>
<H2>4.2 Program documentation</H2>
</a>


<hr>
<A name=4.2.1>
<H3>4.2.1 Environmental dependencies</H3>
</a>

A program shall document the following environmental dependencies, where they
apply, and should document other known environmental dependencies:

<UL>
<LI>considering the pictured numeric output string buffer a fixed area
with unchanging access parameters 
(<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions);
<LI>depending on the presence or absence of non-graphic characters in a
received string 
(<a href=dpans6.htm#6.1.0695>6.1.0695</a> ACCEPT, 
<a href=dpans6.htm#6.2.1390>6.2.1390</a> EXPECT);
<LI>relying on a particular rounding direction 
(<a href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division);
<LI>requiring a particular number representation and arithmetic 
(<a href=dpans3.htm#3.2.1.1>3.2.1.1</a>
Internal number representation);
<LI>requiring non-standard words or techniques 
(<a href=dpans3.htm#3.>3.</a> Usage requirements);
<LI>requiring the ability to send or receive control characters 
(<a href=dpans3.htm#3.1.2.2>3.1.2.2</a> Control characters, 
<a href=dpans6.htm#6.1.1750>6.1.1750</a> KEY);
<LI>using control characters to perform specific functions 
(<a href=dpans6.htm#6.1.1320>6.1.1320</a> EMIT,
<a href=dpans6.htm#6.1.2310>6.1.2310</a> TYPE);
<LI>using flags as arithmetic operands 
(<a href=dpans3.htm#3.1.3.1>3.1.3.1</a> Flags);
<LI>using lower case for standard definition names or depending on the
case sensitivity of a system 
(<a href=dpans3.htm#3.3.1.2>3.3.1.2</a> Definition names);
<LI>using the graphic character with a value of hex 24 
(<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> Graphic
characters).
</UL>

<P>

<hr>
<A name=4.2.2>
<H3>4.2.2 Other program documentation</H3>
</a>

A program shall also document:
<P>

<UL>
<LI>minimum operator's terminal facilities required;
<LI>whether a Standard System exists after the program is loaded.
</UL>


<HR>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans5.htm><IMG   src="right.gif" ></A>  Next Section
<P>
</BODY>
</HTML>
dpans5.htm/     851247060   500   0     100644  3460      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans4.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans6.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=5.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>5. Compliance and labeling</H1>


<hr>
<A name=5.1>
<H2>5.1 ANS Forth systems</H2>
</a>

<p>
<code>
See:
<a href=dpansa5.htm#A.5.1>A.5.1</a> ANS Forth systems
</code>
<p>

<hr>
<A name=5.1.1>
<H3>5.1.1 System compliance</H3>
</a>

A system that complies with all the system requirements given in
sections 
<a href=dpans3.htm#3.>3.</a> Usage requirements and 
<a href=dpans4.htm#4.1>4.1</a> System documentation and their
sub-sections is a Standard System.  An otherwise Standard System that
provides only a portion of the Core words is a Standard System Subset.
An otherwise Standard System (Subset) that fails to comply with one or
more of the minimum values or ranges specified in 
<a href=dpans3.htm#3.>3.</a> Usage requirements
and its sub-sections has environmental restrictions.

<P>

<hr>
<A name=5.1.2>
<H3>5.1.2 System labeling</H3>
</a>

A Standard System (Subset) shall be labeled an <B>ANS Forth System
(Subset)</B>.  That label, by itself, shall not be applied to Standard
Systems or Standard System Subsets that have environmental restrictions.

<P>

The phrase <B>with Environmental Restrictions</B> shall be appended to
the label of a Standard System (Subset) that has environmental
restrictions.

<P>

The phrase <B>Providing name(s) from the Core Extensions word set</B>
shall be appended to the label of any Standard System that provides
portions of the Core Extensions word set.

<P>

The phrase <B>Providing the Core Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
Core Extensions word set.

<P>

<hr>
<A name=5.2>
<H2>5.2 ANS Forth programs</H2>
</a>


<hr>
<A name=5.2.1>
<H3>5.2.1 Program compliance</H3>
</a>

A program that complies with all the program requirements given in
sections 
<a href=dpans3.htm#3.>3.</a> Usage requirements and 
<a href=dpans4.htm#4.2>4.2</a> Program documentation and their
sub-sections is a Standard Program.

<P>

<hr>
<A name=5.2.2>
<H3>5.2.2 Program labeling</H3>
</a>

A Standard Program shall be labeled an <B>ANS Forth Program</B>.  That
label, by itself, shall not be applied to Standard Programs that require
the system to provide standard words outside the Core word set or that
have environmental dependencies.

<P>

The phrase <B>with Environmental Dependencies</B> shall be appended to
the label of Standard Programs that have environmental dependencies.

<P>

The phrase <B>Requiring name(s) from the Core Extensions word set</B>
shall be appended to the label of Standard Programs that require the
system to provide portions of the Core Extensions word set.

<P>

The phrase <B>Requiring the Core Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the Core Extensions word set.

<P>
<code>
See:
<a href=dpansa5.htm#A.5.2.2>A.5.2.2</a> Program labeling
</code>
<p>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans6.htm><IMG   src="right.gif" ></A>  Next Section
<P>
</BODY>
</HTML>
dpans6.htm/     851247180   500   0     100644  90118     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans5.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans7.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=6.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>6. Glossary</H1>

<code><p>
See:
<a href=dpansa6.htm#A.6>A.6</a> Glossary
<p>
</code>

<hr>
<A name=6.1></A>
<H2>6.1 Core words</H2>
</a>



<hr>
<A name=6.1.0010>
<code>
6.1.0010 <B>!</B>
</code>
</a>
<BR>
<B>store</B> CORE
<BR>
<pre>
	( x a-addr -- )
</pre>
<P>

Store x at
a-addr.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0030>
<code>
6.1.0030 <B>#</B>
</code>
</a>
<BR>
<B>number-sign</B>   CORE
<br>
<pre>
	( ud1 -- ud2 )
</pre>
<P>

Divide ud1 by the number in 
<a href=dpans6.htm#6.1.0750>BASE</a> 
giving the quotient ud2 and the
remainder n. (n is the least-significant digit of ud1.) Convert n to
external form and add the resulting character to the beginning of the
pictured numeric output string. An ambiguous condition exists if #
executes outside of a 
<a href=dpans6.htm#6.1.0490>&lt;#</a> 
<a href=dpans6.htm#6.1.0040>#&gt;</a> 
delimited number conversion.

<P>

<code>
See:    
<A href=dpans6.htm#6.1.0050>6.1.0050 #S</a>
</code>

<P>

<hr>
<A name=6.1.0040>
<code>
6.1.0040 <B>#&gt;</B>
</code>
</a>
<BR>
<B>number-sign-greater</B>   CORE
<BR>
<pre>
	( xd -- c-addr u )
</pre>

<P>

Drop xd. Make the pictured numeric output string available as a
character string. c-addr and u specify the resulting character string.
A program may replace characters within the string.

<P>

<code>
See:
<A href=dpans6.htm#6.1.0030>6.1.0030 #</a> ,
<A href=dpans6.htm#6.1.0050>6.1.0050 #S</a> ,
<A href=dpans6.htm#6.1.0490>6.1.0490 &lt;#</a>
</code>

<P>

<hr>
<A name=6.1.0050>
<code>
6.1.0050 <B>#S</B>
</code>
</a>
<BR>
<B>number-sign-s</B> CORE
<BR>
<pre>
	( ud1 -- ud2 )
</pre>

<P>

Convert one digit of ud1 according to the rule for 
<a href=dpans6.htm#6.1.0030>#</a>. Continue
conversion until the quotient is zero. ud2 is zero. An ambiguous
condition exists if #S executes outside of a 
<a href=dpans6.htm#6.1.0490>&lt;#</a> 
<a href=dpans6.htm#6.1.0040>#&gt;</a> 
delimited number
conversion.

<P>


<hr>
<A name=6.1.0070>
<code>
6.1.0070 <B>'</B>
</code>
</a>
<BR>
<B>tick</B>  CORE
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- xt )
</pre>

<P>

Skip leading space delimiters. Parse name delimited by a space. Find
name and return xt, the execution token for name. An ambiguous
condition exists if name is not found.

<P>

When interpreting, <b><code>' xyz EXECUTE</code></b> is equivalent to xyz.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpansa6.htm#A.6.1.2033>A.6.1.2033 POSTPONE</a> ,
<A href=dpans6.htm#6.1.2510>6.1.2510 [']</a> ,
<a href=dpansa6.htm#A.6.1.0070>A.6.1.0070 '</a> ,
<A href=dpansd.htm#D.6.7>D.6.7</a> Immediacy.
</code>

<P>

<hr>
<A name=6.1.0080>
<code>
6.1.0080 <B>(</B>
</code>
</a>
<BR>
<B>paren</B> CORE
<BR>

<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
	Execution: ( <B>"ccc&lt;paren&gt;"</B> -- )
</pre>
<P>

Parse ccc delimited by )
(right parenthesis). ( is an immediate word.

<P>

The number of characters in ccc may be zero to the number of characters
in the parse area.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans11.htm#11.6.1.0080>11.6.1.0080 (</a> ,
<a href=dpansa6.htm#A.6.1.0080>A.6.1.0080 (</a> 
</code>

<P>

<hr>
<A name=6.1.0090>
<code>
6.1.0090 <B>*</B>
</code>
</a>
<BR>
<B>star</B>  CORE
<BR>
<pre>
	( n1|u1 n2|u2 -- n3|u3 )
</pre>

<P>

Multiply n1|u1 by n2|u2
giving the product n3|u3.

<P>

<hr>
<A name=6.1.0100>
<code>
6.1.0100 <B>*/</B>
</code>
</a>
<BR>
<B>star-slash</B>    CORE
<BR>
<pre>
	( n1 n2 n3 -- n4 )
</pre>

<P>

Multiply n1 by n2 producing the intermediate double-cell result d.
Divide d by n3 giving the single-cell quotient n4.  An ambiguous
condition exists if n3 is zero or if the quotient n4 lies outside the
range of a signed number.  If d and n3 differ in sign, the
implementation-defined result returned will be the same as that returned
by either the phrase 
<b><code>
&gt;R M* R&gt; FM/MOD SWAP DROP
</code></b>
or the phrase 
<b><code>
&gt;R M* R&gt; SM/REM SWAP DROP
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division
</code>

<P>

<hr>
<A name=6.1.0110>
<code>
6.1.0110 <B>*/MOD</B>
</code>
</a>
<BR>
<B>star-slash-mod</B>        CORE
<BR>
<pre>
	( n1 n2 n3 -- n4 n5 )
</pre>

<P>

Multiply n1 by n2 producing the intermediate double-cell result d. Divide d
by n3 producing the single-cell remainder n4 and the single-cell quotient n5.
An ambiguous condition exists if n3 is zero, or if the quotient n5 lies
outside the range of a single-cell signed integer. If d and n3 differ in
sign, the implementation-defined result returned will be the same as that
returned by either the phrase 
<b><code>
&gt;R M* R&gt; FM/MOD
</code></b> 
or the phrase 
<b><code>
&gt;R M* R&gt; SM/REM
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division
</code>

<P>

<hr>
<A name=6.1.0120>
<code>
6.1.0120 <B>+</B>
</code>
</a>
<BR>
<B>plus</B>  CORE
<BR>
<pre>
	( n1|u1 n2|u2 -- n3|u3 )
</pre>

<P>

Add n2|u2
to n1|u1, giving the sum n3|u3.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0130>
<code>
6.1.0130 <B>+!</B>
</code>
</a>
<BR>
<B>plus-store</B>    CORE
<BR>
<pre>
	( n|u a-addr -- )
</pre>

<P>

Add n|u
to the single-cell number at a-addr.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0140>
<code>
6.1.0140 <B>+LOOP</B>
</code>
</a>
<BR>
<B>plus-loop</B>     CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: do-sys -- )
</pre>
<P>

Append the run-time semantics given below to the current definition.
Resolve the destination of all unresolved occurrences of 
<a href=dpans6.htm#6.1.1760>LEAVE</a> between
the location given by do-sys and the next location for a transfer of
control, to execute the words following +LOOP.
<P>
<pre>
	Run-time: ( n -- ) ( R: loop-sys1 -- | loop-sys2 )
</pre>
<P>

An ambiguous condition exists if the loop control parameters are
unavailable. Add n to the loop index. If the loop index did not cross
the boundary between the loop limit minus one and the loop limit,
continue execution at the beginning of the loop. Otherwise, discard the
current loop control parameters and continue execution immediately
following the loop.

<P>

<code>
See:    
<A href=dpans6.htm#6.1.1240>6.1.1240 DO</a> ,
<A href=dpans6.htm#6.1.1680>6.1.1680 I</a> ,
<A href=dpans6.htm#6.1.1760>6.1.1760 LEAVE</a> ,
<a href=dpansa6.htm#A.6.1.0140>A.6.1.0140 +LOOP</a>
</code>

<P>

<hr>
<A name=6.1.0150>
<code>
6.1.0150 <B>,</B>
</code>
</a>
<BR>
<B>comma</B> CORE
<BR>
<pre>
	( x -- )
</pre>

<P>

Reserve one cell of data space and store x in the cell. If the data-space
pointer is aligned when , begins execution, it will remain aligned when ,
finishes execution. An ambiguous condition exists if the data-space pointer
is not aligned prior to execution of ,.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space,
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment,
<a href=dpansa6.htm#A.6.1.0150>A.6.1.0150 ,</a>
</code>


<P>

<hr>
<A name=6.1.0160>
<code>
6.1.0160 <B>-</B>
</code>
</a>
<BR>
<B>minus</B> CORE
<BR>
<pre>
	( n1|u1 n2|u2 -- n3|u3 )
</pre>

<P>

Subtract n2|u2
from n1|u1, giving the difference n3|u3.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment.
</code>


<P>

<hr>
<A name=6.1.0180>
<code>
6.1.0180 <B>.</B>
</code>
</a>
<BR>
<B>dot</B>   CORE
<BR>
<pre>
	( n -- )
</pre>

<P>

Display n in
free field format.

<P>

<code>
See:
<A href=dpans3.htm#3.2.1.2>3.2.1.2</a> Digit conversion,
<A href=dpans3.htm#3.2.1.3>3.2.1.3</a> Free-field number display.
</code>

<P>

<hr>
<A name=6.1.0190>
<code>
6.1.0190 <B>."</B>
</code>
</a>
<BR>
<B>dot-quote</B>     CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"ccc&lt;quote&gt;"</B> -- )
</pre>
<P>

Parse ccc delimited by " (double-quote). Append the run-time semantics
given below to the current definition.


<PRE>
        Run-time: ( -- )
</PRE>

<P>

Display
ccc.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.2.0200>6.2.0200 .(</a> ,
<a href=dpansa6.htm#A.6.1.0190>A.6.1.0190 ."</a>
</code>

<P>

<hr>
<A name=6.1.0230>
<code>
6.1.0230 <B>/</B>
</code>
</a>
<BR>
<B>slash</B> CORE
<BR>
<pre>
	( n1 n2 -- n3 )
</pre>

<P>

Divide n1 by n2, giving the single-cell quotient n3. An ambiguous
condition exists if n2 is zero. If n1 and n2 differ in sign, the
implementation-defined result returned will be the same as that returned
by either the phrase 
<b><code>
&gt;R S&gt;D R&gt; FM/MOD SWAP DROP
</code></b> 
or the phrase
<b><code>
&gt;R S&gt;D R&gt; SM/REM SWAP DROP
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division
</code>

<P>

<hr>
<A name=6.1.0240>
<code>
6.1.0240 <B>/MOD</B>
</code>
</a>
<BR>
<B>slash-mod</B>     CORE
<BR>
<pre>
	( n1 n2 -- n3 n4 )
</pre>

<P>

Divide n1 by n2, giving the single-cell remainder n3 and the single-cell
quotient n4. An ambiguous condition exists if n2 is zero. If n1 and n2
differ in sign, the implementation-defined result returned will be the
same as that returned by either the phrase 
<b><code>
&gt;R S&gt;D R&gt; FM/MOD
</code></b>
or the phrase 
<b><code>
&gt;R S&gt;D R&gt; SM/REM
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division
</code>

<P>

<hr>
<A name=6.1.0250>
<code>
6.1.0250 <B>0&lt;</B>
</code>
</a>
<BR>
<B>zero-less</B>     CORE
<BR>
<pre>
	( n -- flag )
</pre>

<P>

flag is true
if and only if n is less than zero.

<P>

<hr>
<A name=6.1.0270>
<code>
6.1.0270 <B>0=</B>
</code>
</a>
<BR>
<B>zero-equals</B>   CORE
<BR>
<pre>
	( x -- flag )
</pre>

<P>

flag is
true if and only if x is equal to zero.

<P>

<hr>
<A name=6.1.0290>
<code>
6.1.0290 <B>1+</B>
</code>
</a>
<BR>
<B>one-plus</B>      CORE
<BR>
<pre>
	( n1|u1 -- n2|u2 )
</pre>

<P>

Add one (1)
to n1|u1 giving the sum n2|u2.

<P>

<hr>
<A name=6.1.0300>
<code>
6.1.0300 <B>1-</B>
</code>
</a>
<BR>
<B>one-minus</B>     CORE
<BR>
<pre>
	( n1|u1 -- n2|u2 )
</pre>

<P>

Subtract one (1)
from n1|u1 giving the difference n2|u2.

<P>

<hr>
<A name=6.1.0310>
<code>
6.1.0310 <B>2!</B>
</code>
</a>
<BR>
<B>two-store</B>     CORE
<BR>
<pre>
	( x1 x2 a-addr -- )
</pre>

<P>

Store the cell pair x1 x2 at a-addr, with x2 at a-addr and x1 at the next
consecutive cell. It is equivalent to the sequence 
<b><code>
SWAP OVER ! CELL+ !
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0320>
<code>
6.1.0320 <B>2*</B>
</code>
</a>
<BR>
<B>two-star</B>      CORE
<BR>
<pre>
	( x1 -- x2 )
</pre>

<P>

x2 is the result of shifting x1 one bit toward the most-significant bit,
filling the vacated least-significant bit with zero.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.0320>A.6.1.0320 2*</a>
</code>
<p>

<hr>
<A name=6.1.0330>
<code>
6.1.0330 <B>2/</B>
</code>
</a>
<BR>
<B>two-slash</B>     CORE
<BR>
<pre>
	( x1 -- x2 )
</pre>

<P>

x2 is the result of shifting x1 one bit toward the least-significant
bit, leaving the most-significant bit unchanged.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.0330>A.6.1.0330 2/</a>
</code>
<p>

<hr>
<A name=6.1.0350>
<code>
6.1.0350 <B>2@</B>
</code>
</a>
<BR>
<B>two-fetch</B>     CORE
<BR>
<pre>
	( a-addr -- x1 x2 )
</pre>

<P>

Fetch the cell pair x1 x2 stored at a-addr. x2 is stored at a-addr and
x1 at the next consecutive cell. It is equivalent to the sequence 
<b><code>
DUP CELL+ @ SWAP @
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment,
<A href=dpans6.htm#6.1.0310>6.1.0310 2!</a> ,
<a href=dpansa6.htm#A.6.1.0350>A.6.1.0350 2@</a>
</code>

<P>

<hr>
<A name=6.1.0370>
<code>
6.1.0370 <B>2DROP</B>
</code>
</a>
<BR>
<B>two-drop</B>      CORE
<BR>
<pre>
	( x1 x2 -- )
</pre>

<P>

Drop cell
pair x1 x2 from the stack.

<P>

<hr>
<A name=6.1.0380>
<code>
6.1.0380 <B>2DUP</B>
</code>
</a>
<BR>
<B>two-dupe</B>      CORE
<BR>
<pre>
	( x1 x2 -- x1 x2 x1 x2 )
</pre>

<P>

Duplicate cell
pair x1 x2.

<P>

<hr>
<A name=6.1.0400>
<code>
6.1.0400 <B>2OVER</B>
</code>
</a>
<BR>
<B>two-over</B>      CORE
<BR>
<pre>
	( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 )
</pre>

<P>

Copy cell
pair x1 x2 to the top of the stack.

<P>

<hr>
<A name=6.1.0430>
<code>
6.1.0430 <B>2SWAP</B>
</code>
</a>
<BR>
<B>two-swap</B>      CORE
<BR>
<pre>
	( x1 x2 x3 x4 -- x3 x4 x1 x2 )
</pre>

<P>

Exchange the
top two cell pairs.

<P>

<hr>
<A name=6.1.0450>
<code>
6.1.0450 <B>:</B>
</code>
</a>
<BR>
<B>colon</B> CORE
<BR>
<pre>
	( C: <B>"&lt;spaces&gt;name"</B> -- colon-sys )
</pre>

<P>

Skip leading space delimiters. Parse name delimited by a space. Create
a definition for name, called a <B>colon definition</B>. Enter
compilation state and start the current definition, producing colon-sys.
Append the initiation semantics given below to the current definition.

<P>

The execution semantics of name will be determined by the words compiled
into the body of the definition. The current definition shall not be
findable in the dictionary until it is ended (or until the execution of
<a href=dpans6.htm#6.1.1250>DOES&gt;</a> 
in some systems).
<P>
<pre>
	Initiation: ( i*x -- i*x )  ( R:  -- nest-sys )
</pre>
<P>

Save implementation-dependent information nest-sys about the calling
definition. The stack effects i*x represent arguments to name.

<P>
<pre>
	<i>name</i> Execution: ( i*x -- j*x )
</pre>
<P>

Execute the definition name. The stack effects i*x and j*x represent
arguments to and results from name, respectively.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans3.htm#3.4.5>3.4.5</a> Compilation,
<A href=dpans6.htm#6.1.2500>6.1.2500 [</a> ,
<A href=dpans6.htm#6.1.2540>6.1.2540 ]</a> ,
<A href=dpans15.htm#15.6.2.0470>15.6.2.0470 ;CODE</a> ,
<a href=dpansa6.htm#A.6.1.0450>A.6.1.0450 :</a> ,
<a href=a0005.htm>RFI 0005</a> Initiation semantics.
</code>


<P>

<hr>
<A name=6.1.0460>
<code>
6.1.0460 <B>;</B>
</code>
</a>
<BR>
<B>semicolon</B>     CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: colon-sys -- )
</pre>
<P>

Append the run-time semantics below to the current definition. End the
current definition, allow it to be found in the dictionary and enter
interpretation state, consuming colon-sys. If the data-space pointer is
not aligned, reserve enough data space to align it.

<P>
<pre>
	Run-time: ( -- ) ( R: nest-sys -- )
</pre>
<P>

Return to
the calling definition specified by nest-sys.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans3.htm#3.4.5>3.4.5</a> Compilation,
<a href=dpansa6.htm#A.6.1.0460>A.6.1.0460 ;</a>
</code>

<P>

<hr>
<A name=6.1.0480>
<code>
6.1.0480 <B>&lt;</B>
</code>
</a>
<BR>
<B>less-than</B>     CORE
<BR>
<pre>
	( n1 n2 -- flag )
</pre>

<P>

flag is
true if and only if n1 is less than n2.

<P>

<code>
See:    
<A href=dpans6.htm#6.1.2340>6.1.2340 U&lt;</a>
</code>

<P>

<hr>
<A name=6.1.0490>
<code>
6.1.0490 <B>&lt;#</B>
</code>
</a>
<BR>
<B>less-number-sign</B>      CORE
<BR>
<pre>
	( -- )
</pre>

<P>

Initialize the
pictured numeric output conversion process.

<P>

<code>
See:    
<A href=dpans6.htm#6.1.0030>6.1.0030 #</a> ,
<A href=dpans6.htm#6.1.0040>6.1.0040 #&gt;</a> ,
<A href=dpans6.htm#6.1.0050>6.1.0050 #S</a>
</code>

<P>

<hr>
<A name=6.1.0530>
<code>
6.1.0530 <B>=</B>
</code>
</a>
<BR>
<B>equals</B>        CORE
<BR>
<pre>
	( x1 x2 -- flag )
</pre>

<P>

flag is true
if and only if x1 is bit-for-bit the same as x2.

<P>

<hr>
<A name=6.1.0540>
<code>
6.1.0540 <B>&gt;</B>
</code>
</a>
<BR>
<B>greater-than</B>  CORE
<BR>
<pre>
	( n1 n2 -- flag )
</pre>

<P>

flag is true
if and only if n1 is greater than n2.

<P>

<code>
See:    
<A href=dpans6.htm#6.2.2350>6.2.2350 U&gt;</a>
</code>

<P>

<hr>
<A name=6.1.0550>
<code>
6.1.0550 <B>&gt;BODY</B>
</code>
</a>
<BR>
<B>to-body</B>       CORE
<BR>
<pre>
	( xt -- a-addr )
</pre>

<P>

a-addr is the data-field address corresponding to xt. An ambiguous
condition exists if xt is not for a word defined via 
<a href=dpans6.htm#6.1.1000>CREATE</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space,
<a href=dpansa6.htm#A.6.1.0550>A.6.1.0550 &gt;BODY</a>
</code>


<P>

<hr>
<A name=6.1.0560>
<code>
6.1.0560 <B>&gt;IN</B>
</code>
</a>
<BR>
<B>to-in</B> CORE
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr is the address of a cell containing the offset in characters from
the start of the input buffer to the start of the parse area.

<P>

<hr>
<A name=6.1.0570>
<code>
6.1.0570 <B>&gt;NUMBER</B>
</code>
</a>
<BR>
<B>to-number</B>      CORE
<BR>
<pre>
	( ud1 c-addr1 u1 -- ud2 c-addr2 u2 )
</pre>

<P>

ud2 is the unsigned result of converting the characters within the
string specified by c-addr1 u1 into digits, using the number in 
<a href=dpans6.htm#6.1.0750>BASE</a>,
and adding each into ud1 after multiplying ud1 by the number in BASE.
Conversion continues left-to-right until a character that is not
convertible, including any <B>+</B> or <B>-</B>, is encountered or the
string is entirely converted. c-addr2 is the location of the first
unconverted character or the first character past the end of the string
if the string was entirely converted. u2 is the number of unconverted
characters in the string. An ambiguous condition exists if ud2
overflows during the conversion.

<P>

<code>
See:
<A href=dpans3.htm#3.2.1.2>3.2.1.2</a> Digit conversion
</code>

<P>

<hr>
<A name=6.1.0580>
<code>
6.1.0580 <B>&gt;R</B>
</code>
</a>
<BR>
<B>to-r</B>  CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( x -- ) ( R:  -- x )
</pre>
<P>

Move x to
the return stack.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<A href=dpans6.htm#6.1.2060>6.1.2060 R&gt;</a> ,
<A href=dpans6.htm#6.1.2070>6.1.2070 R@</a> ,
<A href=dpans6.htm#6.2.0340>6.2.0340 2&gt;R</a> ,
<A href=dpans6.htm#6.2.0410>6.2.0410 2R&gt;</a> ,
<A href=dpans6.htm#6.2.0415>6.2.0415 2R@</a> 
</code>
<P>

<hr>
<A name=6.1.0630>
<code>
6.1.0630 <B>?DUP</B>
</code>
</a>
<BR>
<B>question-dupe</B> CORE
<BR>
<pre>
	( x -- 0 | x x )
</pre>

<P>

Duplicate x
if it is non-zero.

<P>

<hr>
<A name=6.1.0650>
<code>
6.1.0650 <B>@</B>
</code>
</a>
<BR>
<B>fetch</B> CORE
<BR>
<pre>
	( a-addr -- x )
</pre>

<P>

x is the
value stored at a-addr.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0670>
<code>
6.1.0670 <B>ABORT</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( i*x -- ) ( R: j*x -- )
</pre>

<P>

Empty the data stack and perform the function of 
<a href=dpans6.htm#6.1.2050>QUIT</a>, which includes
emptying the return stack, without displaying a message.

<P>

<code>
See:    
<A href=dpans9.htm#9.6.2.0670>9.6.2.0670 ABORT</a>
</code>

<P>

<hr>
<A name=6.1.0680>
<code>
6.1.0680 <B>ABORT"</B>
</code>
</a>
<BR>
<B>abort-quote</B>   CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"ccc&lt;quote&gt;"</B> -- )
</pre>
<P>

Parse ccc delimited by a " (double-quote). Append the run-time semantics
given below to the current definition.

<p>
<pre>
	Run-time: ( i*x x1 --  | i*x ) ( R: j*x --  | j*x )
</pre>
<P>

Remove x1 from the stack. If any bit of x1 is not zero, display ccc and
perform an implementation-defined abort sequence that includes the
function of 
<a href=dpans6.htm#6.1.0670>ABORT</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans9.htm#9.6.2.0680>9.6.2.0680 ABORT"</a> ,
<a href=dpansa6.htm#A.6.1.0680>A.6.1.0680 ABORT"</a>
</code>

<P>

<hr>
<A name=6.1.0690>
<code>
6.1.0690 <B>ABS</B>
</code>
</a>
<BR>
<B>abs</B>   CORE
<BR>
<pre>
	( n -- u )
</pre>

<P>

u is the
absolute value of n.

<P>

<hr>
<A name=6.1.0695>
<code>
6.1.0695 <B>ACCEPT</B>
</code>
</a>
<BR>
CORE
<pre>
	( c-addr +n1 -- +n2 )
</pre>

<P>

Receive a string of at most +n1 characters. An ambiguous condition
exists if +n1 is zero or greater than 32,767. Display graphic
characters as they are received. A program that depends on the presence
or absence of non-graphic characters in the string has an environmental
dependency. The editing functions, if any, that the system performs in
order to construct the string are implementation-defined.

<P>

Input terminates when an implementation-defined line terminator is
received. When input terminates, nothing is appended to the string, and
the display is maintained in an implementation-defined way.

<P>

+n2 is the
length of the string stored at c-addr.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.0695>A.6.1.0695 ACCEPT</a>
</code>
<p>

<hr>
<A name=6.1.0705>
<code>
6.1.0705 <B>ALIGN</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- )
</pre>

<P>

If the data-space pointer is not aligned, reserve enough space to align
it.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space,
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment,
<a href=dpansa6.htm#A.6.1.0705>A.6.1.0705 ALIGN</a>
</code>


<P>

<hr>
<A name=6.1.0706>
<code>
6.1.0706 <B>ALIGNED</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( addr -- a-addr )
</pre>

<P>

a-addr
is the first aligned address greater than or equal to addr.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment,
<a href=dpans6.htm#6.1.0705>6.1.0705 ALIGN</a>
</code>


<P>

<hr>
<A name=6.1.0710>
<code>
6.1.0710 <B>ALLOT</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n -- )
</pre>

<P>

If n is greater than zero, reserve n address units of data space. If n
is less than zero, release |n| address units of data space. If n is
zero, leave the data-space pointer unchanged.

<P>

If the data-space pointer is aligned and n is a multiple of the size of
a cell when ALLOT begins execution, it will remain aligned when ALLOT
finishes execution.

<P>

If the data-space pointer is character aligned and n is a multiple of
the size of a character when ALLOT begins execution, it will remain
character aligned when ALLOT finishes execution.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space
</code>

<P>

<hr>
<A name=6.1.0720>
<code>
6.1.0720 <B>AND</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x1 x2 -- x3 )
</pre>

<P>

x3 is
the bit-by-bit logical <B>and</B> of x1 with x2.

<P>

<hr>
<A name=6.1.0750>
<code>
6.1.0750 <B>BASE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr is the address of a cell containing the current number-conversion
radix {{2...36}}.

<P>

<hr>
<A name=6.1.0760>
<code>
6.1.0760 <B>BEGIN</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: -- dest )
</pre>
<P>

Put the next location for a transfer of control, dest, onto the control
flow stack. Append the run-time semantics given below to the current
definition.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue
execution.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control-flow stack,
<A href=dpans6.htm#6.1.2140>6.1.2140 REPEAT</a> ,
<A href=dpans6.htm#6.1.2390>6.1.2390 UNTIL</a> ,
<A href=dpans6.htm#6.1.2430>6.1.2430 WHILE</a> ,
<a href=dpansa6.htm#A.6.1.0760>A.6.1.0760 BEGIN</a>
</code>

<P>

<hr>
<A name=6.1.0770>
<code>
6.1.0770 <B>BL</B>
</code>
</a>
<BR>
<B>b-l</B>   CORE
<BR>
<pre>
	( -- char )
</pre>

<P>

char is
the character value for a space.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.0770>A.6.1.0770 BL</a>
</code>
<p>

<hr>
<A name=6.1.0850>
<code>
6.1.0850 <B>C!</B>
</code>
</a>
<BR>
<B>c-store</B>       CORE
<BR>
<pre>
	( char c-addr -- )
</pre>

<P>

Store char at c-addr. When character size is smaller than cell size,
only the number of low-order bits corresponding to character size are
transferred.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0860>
<code>
6.1.0860 <B>C,</B>
</code>
</a>
<BR>
<B>c-comma</B>       CORE
<BR>
<pre>
	( char -- )
</pre>

<P>

Reserve space for one character in the data space and store char in the
space. If the data-space pointer is character aligned when C, begins
execution, it will remain character aligned when C, finishes execution.
An ambiguous condition exists if the data-space pointer is not
character-aligned prior to execution of C,.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space,
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment.
</code>

<P>

<hr>
<A name=6.1.0870>
<code>
6.1.0870 <B>C@</B>
</code>
</a>
<BR>
<B>c-fetch</B>       CORE
<BR>
<pre>
	( c-addr -- char )
</pre>

<P>

Fetch the character stored at c-addr. When the cell size is greater
than character size, the unused high-order bits are all zeroes.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0880>
<code>
6.1.0880 <B>CELL+</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( a-addr1 -- a-addr2 )
</pre>

<P>

Add the
size in address units of a cell to a-addr1, giving a-addr2.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment,
<a href=dpansa6.htm#A.6.1.0880>A.6.1.0880 CELL+</a>
</code>


<P>

<hr>
<A name=6.1.0890>
<code>
6.1.0890 <B>CELLS</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n1 -- n2 )
</pre>

<P>

n2 is
the size in address units of n1 cells.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.0890>A.6.1.0890 CELLS</a>
</code>
<p>

<hr>
<A name=6.1.0895>
<code>
6.1.0895 <B>CHAR</B>
</code>
</a>
<BR>
<B>char</B>  CORE
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- char )
</pre>

<P>

Skip leading
space delimiters. Parse name delimited by a space. Put the
value of its first character onto the stack.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.1.2520>6.1.2520 [CHAR]</a> ,
<a href=dpansa6.htm#A.6.1.0895>A.6.1.0895 CHAR</a>
</code>

<P>

<hr>
<A name=6.1.0897>
<code>
6.1.0897 <B>CHAR+</B>
</code>
</a>
<BR>
<B>char-plus</B>     CORE
<BR>
<pre>
	( c-addr1 -- c-addr2 )
</pre>

<P>

Add the
size in address units of a character to c-addr1, giving c-addr2.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment
</code>

<P>

<hr>
<A name=6.1.0898>
<code>
6.1.0898 <B>CHARS</B>
</code>
</a>
<BR>
<B>chars</B> CORE
<BR>
<pre>
	( n1 -- n2 )
</pre>

<P>

n2 is
the size in address units of n1 characters.


<P>

<hr>
<A name=6.1.0950>
<code>
6.1.0950 <B>CONSTANT</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading
space delimiters. Parse name delimited by a space. Create a
definition for name with the execution semantics defined below.

<P>

name is
referred to as a <B>constant</B>.

<P>
<pre>
	<i>name</i> Execution: ( -- x )
</pre>
<P>

Place x
on the stack.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa6.htm#A.6.1.0950>A.6.1.0950 CONSTANT</a>
</code>

<P>

<hr>
<A name=6.1.0980>
<code>
6.1.0980 <B>COUNT</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( c-addr1 -- c-addr2 u )
</pre>

<P>

Return the
character string specification for the counted string stored at
c-addr1. c-addr2 is the address of the first character after c-addr1. u is
the contents of the character at c-addr1, which is the length in characters of
the string at c-addr2.

<P>

<hr>
<A name=6.1.0990>
<code>
6.1.0990 <B>CR</B>
</code>
</a>
<BR>
<B>c-r</B>   CORE
<BR>
<pre>
	( -- )
</pre>

<P>

Cause subsequent
output to appear at the beginning of the next line.

<P>

<hr>
<A name=6.1.1000>
<code>
6.1.1000 <B>CREATE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading
space delimiters. Parse name delimited by a space. Create a
definition for name with the execution semantics defined below. If the
data-space pointer is not aligned, reserve enough data space to align it. The
new data-space pointer defines name's data field. CREATE does not allocate
data space in name's data field.

<P>
<pre>
	<i>name</i> Execution: ( -- a-addr )
</pre>
<P>

a-addr is the address of name's data field. The execution semantics of name
may be extended by using 
<a href=dpans6.htm#6.1.1250>DOES&gt;</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data space,
<a href=dpansa6.htm#A.6.1.1000>A.6.1.1000 CREATE</a>
</code>

<P>

<hr>
<A name=6.1.1170>
<code>
6.1.1170 <B>DECIMAL</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- )
</pre>

<P>

Set the
numeric conversion radix to ten (decimal).

<P>

<hr>
<A name=6.1.1200>
<code>
6.1.1200 <B>DEPTH</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- +n )
</pre>

<P>

+n is the number of single-cell values contained in the data stack
before +n was placed on the stack.

<P>

<hr>
<A name=6.1.1240>
<code>
6.1.1240 <B>DO</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: -- do-sys )
</pre>
<P>

Place do-sys onto the control-flow stack. Append the run-time semantics
given below to the current definition. The semantics are incomplete
until resolved by a consumer of do-sys such as 
<a href=dpans6.htm#6.1.1800>LOOP</a>.

<P>
<pre>
	Run-time: ( n1|u1 n2|u2 -- ) ( R: -- loop-sys )
</pre>
<P>

Set up loop control parameters with index n2|u2 and limit n1|u1. An
ambiguous condition exists if n1|u1 and n2|u2 are not both the same
type. Anything already on the return stack becomes unavailable until
the loop-control parameters are discarded.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control-flow stack,
<A href=dpans6.htm#6.1.0140>6.1.0140 +LOOP</a> ,
<a href=dpansa6.htm#A.6.1.1240>A.6.1.1240 DO</a>
</code>

<P>

<hr>
<A name=6.1.1250>
<code>
6.1.1250 <B>DOES&gt;</B>
</code>
</a>
<BR>
<B>does</B>  CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: colon-sys1 -- colon-sys2 )
</pre>
<P>

Append the run-time semantics below to the current definition. Whether
or not the current definition is rendered findable in the dictionary by
the compilation of DOES&gt; is implementation defined. Consume
colon-sys1 and produce colon-sys2. Append the initiation semantics
given below to the current definition.

<P>
<pre>
	Run-time: ( -- ) ( R: nest-sys1 -- )
</pre>
<P>

Replace the execution semantics of the most recent definition, referred
to as name, with the name execution semantics given below. Return
control to the calling definition specified by nest-sys1. An ambiguous
condition exists if name was not defined with 
<a href=dpans6.htm#6.1.1000>CREATE</a> 
or a user-defined
word that calls CREATE.

<P>
<pre>
	Initiation: ( i*x -- i*x a-addr ) ( R:  -- nest-sys2 )
</pre>
<P>

Save implementation-dependent information nest-sys2 about the calling
definition. Place name's data field address on the stack. The stack
effects i*x represent arguments to name.

<P>
<pre>
	<i>name</i> Execution: ( i*x -- j*x )
</pre>
<P>

Execute the portion of the definition that begins with the initiation
semantics appended by the DOES&gt; which modified name. The stack
effects i*x and j*x represent arguments to and results from name,
respectively.

<P>

<code>
See:
<a href=dpansa6.htm#A.6.1.1250>A.6.1.1250 DOES&gt;</a> ,
<a href=a0003.htm>RFI 0003</a> Defining words etc.,
<a href=a0005.htm>RFI 0005</a> Initiation semantics.
</code>

<P>

<hr>
<A name=6.1.1260>
<code>
6.1.1260 <B>DROP</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x -- )
</pre>

<P>

Remove x
from the stack.

<P>

<hr>
<A name=6.1.1290>
<code>
6.1.1290 <B>DUP</B>
</code>
</a>
<BR>
<B>dupe</B>  CORE
<BR>
<pre>
	( x -- x x )
</pre>

<P>

Duplicate
x.

<P>

<hr>
<A name=6.1.1310>
<code>
6.1.1310 <B>ELSE</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: orig1 -- orig2 )
</pre>
<P>

Put the location of a new unresolved forward reference orig2 onto the
control flow stack. Append the run-time semantics given below to the
current definition. The semantics will be incomplete until orig2 is
resolved (e.g., by 
<a href=dpans6.htm#6.1.2270>THEN</a>). 
Resolve the forward reference orig1 using the
location following the appended run-time semantics.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue execution at the location given by the resolution of orig2.

<P>

<code>
See:
<A href=dpans6.htm#6.1.1700>6.1.1700 IF</a> ,
<a href=dpansa6.htm#A.6.1.1310>A.6.1.1310 ELSE</a>
</code>

<P>

<hr>
<A name=6.1.1320>
<code>
6.1.1320 <B>EMIT</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x -- )
</pre>

<P>

If x is a graphic character in the implementation-defined character set,
display x. The effect of EMIT for all other values of x is
implementation-defined.

<P>

When passed a character whose character-defining bits have a value
between hex 20 and 7E inclusive, the corresponding standard character,
specified by 
<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> 
Graphic characters, is displayed. Because
different output devices can respond differently to control characters,
programs that use control characters to perform specific functions have
an environmental dependency. Each EMIT deals with only one character.

<P>

<code>
See:    
<A href=dpans6.htm#6.1.2310>6.1.2310 TYPE</a>
</code>

<P>

<hr>
<A name=6.1.1345>
<code>
6.1.1345 <B>ENVIRONMENT?</B>
</code>
</a>
<BR>
<B>environment-query</B>     CORE
<BR>
<pre>
	( c-addr u -- false | i*x true )
</pre>

<P>

c-addr is the address of a character string and u is the string's
character count. u may have a value in the range from zero to an
implementation-defined maximum which shall not be less than 31. The
character string should contain a keyword from 
<a href=dpans3.htm#3.2.6>3.2.6</a> Environmental
queries or the optional word sets to be checked for correspondence with
an attribute of the present environment. If the system treats the
attribute as unknown, the returned flag is false; otherwise, the flag is
true and the i*x returned is of the type specified in the table for the
attribute queried.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.1345>A.6.1.1345 ENVIRONMENT?</a>
</code>
<p>

<hr>
<A name=6.1.1360>
<code>
6.1.1360 <B>EVALUATE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( i*x c-addr u -- j*x )
</pre>

<P>

Save the current input source specification. Store minus-one (-1) in
<a href=dpans6.htm#6.2.2218>SOURCE-ID</a> 
if it is present. Make the string described by c-addr and u
both the input source and input buffer, set 
<a href=dpans6.htm#6.1.0560>&gt;IN</a> 
to zero, and
interpret. When the parse area is empty, restore the prior input source
specification. Other stack effects are due to the words EVALUATEd.

<P>
<code>
See:
<a href=dpans7.htm#7.6.1.1360>7.6.1.1360 EVALUATE</a> ,
<a href=dpansa6.htm#A.6.1.1360>A.6.1.1360 EVALUATE</a> ,
<a href=a0006.htm>RFI 0006</a> Writing to Input Buffers.
</code>
<p>

<hr>
<A name=6.1.1370>
<code>
6.1.1370 <B>EXECUTE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( i*x xt -- j*x )
</pre>

<P>

Remove xt from the stack and perform the semantics identified by it.
Other stack effects are due to the word EXECUTEd.

<P>

<code>
See:
<A href=dpans6.htm#6.1.0070>6.1.0070 '</a> ,
<A href=dpans6.htm#6.1.2510>6.1.2510 [']</a>
</code>

<P>

<hr>
<A name=6.1.1380>
<code>
6.1.1380 <B>EXIT</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- ) ( R: nest-sys -- )
</pre>
<P>

Return control to the calling definition specified by nest-sys. Before
executing EXIT within a do-loop, a program shall discard the loop-control
parameters by executing 
<a href=dpans6.htm#6.1.2380>UNLOOP</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<a href=dpansa6.htm#A.6.1.1380>A.6.1.1380 EXIT</a>
</code>

<P>

<hr>
<A name=6.1.1540>
<code>
6.1.1540 <B>FILL</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( c-addr u char -- )
</pre>

<P>

If u
is greater than zero, store char in each of u consecutive characters of
memory beginning at c-addr.

<P>

<hr>
<A name=6.1.1550>
<code>
6.1.1550 <B>FIND</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( c-addr -- c-addr 0  |  xt 1  |  xt -1 )
</pre>

<P>

Find the definition named in the counted string at c-addr. If the
definition is not found, return c-addr and zero. If the definition is
found, return its execution token xt. If the definition is immediate,
also return one (1), otherwise also return minus-one (-1). For a given
string, the values returned by FIND while compiling may differ from
those returned while not compiling.

<P>

<code>
See:
<A href=dpans3.htm#3.4.2>3.4.2</a> Finding definition names,
<A href=dpans6.htm#6.1.0070>6.1.0070 '</a> ,
<A href=dpans6.htm#6.1.2510>6.1.2510 [']</a> ,
<a href=dpansa6.htm#A.6.1.1550>A.6.1.1550 FIND</a> ,
<A href=dpansa6.htm#A.6.1.2033>A.6.1.2033 POSTPONE</a> ,
<A href=dpansd.htm#D.6.7>D.6.7</a> Immediacy.
</code>

<P>

<hr>
<A name=6.1.1561>
<code>
6.1.1561 <B>FM/MOD</B>
</code>
</a>
<BR>
<B>f-m-slash-mod</B> CORE
<BR>
<pre>
	( d1 n1 -- n2 n3 )
</pre>

<P>

Divide d1 by n1, giving the floored quotient n3 and the remainder n2.
Input and output stack arguments are signed. An ambiguous condition
exists if n1 is zero or if the quotient lies outside the range of a
single-cell signed integer.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division,
<A href=dpans6.htm#6.1.2214>6.1.2214 SM/REM</a> ,
<A href=dpans6.htm#6.1.2370>6.1.2370 UM/MOD</a> ,
<a href=dpansa6.htm#A.6.1.1561>A.6.1.1561 FM/MOD</a>
</code>

<P>

<hr>
<A name=6.1.1650>
<code>
6.1.1650 <B>HERE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- addr )
</pre>

<P>

addr is
the data-space pointer.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.2>3.3.3.2</a> Contiguous regions
</code>

<P>

<hr>
<A name=6.1.1670>
<code>
6.1.1670 <B>HOLD</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( char -- )
</pre>

<P>

Add char
to the beginning of the pictured numeric output string. An ambiguous
condition exists if HOLD executes outside of a 
<a href=dpans6.htm#6.1.0490>&lt;#</a> 
<a href=dpans6.htm#6.1.0040>#&gt;</a> 
delimited number
conversion.

<P>

<hr>
<A name=6.1.1680>
<code>
6.1.1680 <B>I</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- n|u ) ( R:  loop-sys -- loop-sys )
</pre>
<P>

n|u is a copy of the current (innermost) loop index. An ambiguous condition
exists if the loop control parameters are unavailable.

<P>

<hr>
<A name=6.1.1700>
<code>
6.1.1700 <B>IF</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: -- orig )
</pre>
<P>

Put the location of a new unresolved forward reference orig onto the
control flow stack. Append the run-time semantics given below to the
current definition. The semantics are incomplete until orig is
resolved, e.g., by 
<a href=dpans6.htm#6.1.2270>THEN</a> or 
<a href=dpans6.htm#6.1.1310>ELSE</a>.

<P>
<pre>
	Run-time: ( x -- )
</pre>
<P>

If all bits of x are zero, continue execution at the location specified
by the resolution of orig.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control flow stack,
<a href=dpansa6.htm#A.6.1.1700>A.6.1.1700 IF</a>
</code>

<P>

<hr>
<A name=6.1.1710>
<code>
6.1.1710 <B>IMMEDIATE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- )
</pre>

<P>

Make the
most recent definition an immediate word. An ambiguous condition
exists if the most recent definition does not have a name.

<P>

<code>
See:
<a href=dpansa6.htm#A.6.1.1710>A.6.1.1710 IMMEDIATE</a> ,
<A href=dpansd.htm#D.6.7>D.6.7</a> Immediacy,
<a href=a0007.htm>RFI 0007</a> Distinction between <em>immediacy</em> and <em>special compilation semantics</em>.
</code>

<P>

<hr>
<A name=6.1.1720>
<code>
6.1.1720 <B>INVERT</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x1 -- x2 )
</pre>

<P>

Invert all
bits of x1, giving its logical inverse x2.

<P>

<code>
See:
<A href=dpans6.htm#6.1.1910>6.1.1910 NEGATE</a> ,
<A href=dpans6.htm#6.1.0270>6.1.0270 0=</a> ,
<a href=dpansa6.htm#A.6.1.1720>A.6.1.1720 INVERT</a>
</code>

<P>

<hr>
<A name=6.1.1730>
<code>
6.1.1730 <B>J</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- n|u ) ( R: loop-sys1 loop-sys2 -- loop-sys1 loop-sys2 )
</pre>
<P>

n|u is a copy of the next-outer loop index. An ambiguous condition
exists if the loop control parameters of the next-outer loop, loop-sys1,
are unavailable.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.1730>A.6.1.1730 J</a>
</code>
<p>

<hr>
<A name=6.1.1750>
<code>
6.1.1750 <B>KEY</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- char )
</pre>

<P>

Receive one character char, a member of the implementation-defined
character set. Keyboard events that do not correspond to such
characters are discarded until a valid character is received, and those
events are subsequently unavailable.

<P>

All standard characters can be received. Characters received by KEY are
not displayed.

<P>

Any standard character returned by KEY has the numeric value specified
in 
<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> 
Graphic characters. Programs that require the ability to
receive control characters have an environmental dependency.

<P>

<code>
See:
<A href=dpans10.htm#10.6.2.1305>10.6.2.1305 EKEY</a> ,
<A href=dpans10.htm#10.6.1.1755>10.6.1.1755 KEY?</a>
</code>

<P>

<hr>
<A name=6.1.1760>
<code>
6.1.1760 <B>LEAVE</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- ) ( R: loop-sys -- )
</pre>
<P>

Discard the current loop control parameters. An ambiguous condition
exists if they are unavailable. Continue execution immediately
following the innermost syntactically enclosing 
<a href=dpans6.htm#6.1.1240>DO</a> ... 
<a href=dpans6.htm#6.1.1800>LOOP</a> 
or DO ...
<a href=dpans6.htm#6.1.0140>+LOOP</a>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<a href=dpansa6.htm#A.6.1.1760>A.6.1.1760 LEAVE</a>
</code>

<P>

<hr>
<A name=6.1.1780>
<code>
6.1.1780 <B>LITERAL</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( x -- )
</pre>
<P>

Append the run-time semantics
given below to the current definition.

<P>
<pre>
	Run-time: ( -- x )
</pre>
<P>

Place x
on the stack.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.1780>A.6.1.1780 LITERAL</a>
</code>
<p>

<hr>
<A name=6.1.1800>
<code>
6.1.1800 <B>LOOP</B>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: do-sys -- )
</pre>
<P>

Append the run-time semantics given below to the current definition.
Resolve the destination of all unresolved occurrences of 
<a href=dpans6.htm#6.1.1760>LEAVE</a> 
between
the location given by do-sys and the next location for a transfer of
control, to execute the words following the LOOP.

<P>
<pre>
	Run-time: ( -- ) ( R:  loop-sys1 --  | loop-sys2 )
</pre>
<P>

An ambiguous condition exists if the loop control parameters are
unavailable. Add one to the loop index. If the loop index is then
equal to the loop limit, discard the loop parameters and continue
execution immediately following the loop. Otherwise continue execution
at the beginning of the loop.

<P>

<code>
See:
<A href=dpans6.htm#6.1.1240>6.1.1240 DO</a> ,
<A href=dpans6.htm#6.1.1680>6.1.1680 I</a> ,
<a href=dpansa6.htm#A.6.1.1800>A.6.1.1800 LOOP</a>
</code>

<P>

<hr>
<A name=6.1.1805>
<code>
6.1.1805 <B>LSHIFT</B>
</code>
</a>
<BR>
<B>l-shift</B>       CORE
<BR>
<pre>
	( x1 u -- x2 )
</pre>

<P>

Perform a
logical left shift of u bit-places on x1, giving x2. Put zeroes
into the least significant bits vacated by the shift. An ambiguous condition
exists if u is greater than or equal to the number of bits in a cell.

<P>

<hr>
<A name=6.1.1810>
<code>
6.1.1810 <B>M*</B>
</code>
</a>
<BR>
<B>m-star</B>        CORE
<BR>
<pre>
	( n1 n2 -- d )
</pre>

<P>

d is
the signed product of n1 times n2.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.1810>A.6.1.1810 M*</a>
</code>
<p>

<hr>
<A name=6.1.1870>
<code>
6.1.1870 <B>MAX</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n1 n2 -- n3 )
</pre>

<P>

n3 is
the greater of n1 and n2.

<P>

<hr>
<A name=6.1.1880>
<code>
6.1.1880 <B>MIN</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n1 n2 -- n3 )
</pre>

<P>

n3 is
the lesser of n1 and n2.

<P>

<hr>
<A name=6.1.1890>
<code>
6.1.1890 <B>MOD</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n1 n2 -- n3 )
</pre>

<P>

Divide n1 by n2, giving the single-cell remainder n3. An ambiguous
condition exists if n2 is zero. If n1 and n2 differ in sign, the
implementation-defined result returned will be the same as that returned
by either the phrase 
<b><code>&gt;R S&gt;D R&gt; FM/MOD DROP</code></b> 
or the phrase 
<b><code>&gt;R S&gt;D R&gt; SM/REM DROP</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division
</code>

<P>

<hr>
<A name=6.1.1900>
<code>
6.1.1900 <B>MOVE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( addr1 addr2 u -- )
</pre>

<P>

If u is greater than zero, copy the contents of u consecutive address
units at addr1 to the u consecutive address units at addr2. After MOVE
completes, the u consecutive address units at addr2 contain exactly what
the u consecutive address units at addr1 contained before the move.

<P>

<code>
See:
<A href=dpans17.htm#17.6.1.0910>17.6.1.0910 CMOVE</a> ,
<A href=dpans17.htm#17.6.1.0920>17.6.1.0920 CMOVE&gt;</a> ,
<a href=dpansa6.htm#A.6.1.1900>A.6.1.1900 MOVE</a>
</code>

<P>

<hr>
<A name=6.1.1910>
<code>
6.1.1910 <B>NEGATE</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n1 -- n2 )
</pre>

<P>

Negate n1,
giving its arithmetic inverse n2.

<P>

<code>
See:
<A href=dpans6.htm#6.1.1720>6.1.1720 INVERT</a> ,
<A href=dpans6.htm#6.1.0270>6.1.0270 0=</a>
</code>

<P>

<hr>
<A name=6.1.1980>
<code>
6.1.1980 <B>OR</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x1 x2 -- x3 )
</pre>

<P>

x3 is
the bit-by-bit inclusive-or of x1 with x2.

<P>

<hr>
<A name=6.1.1990>
<code>
6.1.1990 <B>OVER</B>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x1 x2 -- x1 x2 x1 )
</pre>

<P>

Place a
copy of x1 on top of the stack.

<hr>
<A name=6.1.2033>
<code>
6.1.2033 <B>POSTPONE</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters. Parse name delimited by a space. Find
name. Append the compilation semantics of name to the current
definition. An ambiguous condition exists if name is not found.

<P>

<code>
See:
<a href=dpansd.htm#D.6.7>D.6.7</a> Immediacy,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa6.htm#A.6.1.2033>A.6.1.2033 POSTPONE</a> ,
<a href=dpans6.htm#6.2.2530>6.2.2530 [COMPILE]</a>
</code>

<P>


<hr>
<A name=6.1.2050>
<code>
6.1.2050 <b>QUIT</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- )  ( R:  i*x -- )
</pre>

<P>

Empty the return stack, store zero in 
<a href=dpans6.htm#6.2.2218>SOURCE-ID</a> 
if it is present, make
the user input device the input source, and enter interpretation state.
Do not display a message. Repeat the following:

<UL>
<LI>Accept a line from the input source into the input buffer, set 
<a href=dpans6.htm#6.1.0560>&gt;IN</a>
to zero, and interpret.
<LI>Display the implementation-defined system prompt if in interpretation
state, all processing has been completed, and no ambiguous condition
exists.
</ul>
<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter
</code>

<P>

<hr>
<A name=6.1.2060>
<code>
6.1.2060 <b>R&gt;</b>
</code>
</a>
<BR>
<B>r-from</B>        CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- x ) ( R:  x -- )
</pre>
<P>

Move x from
the return stack to the data stack.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<A href=dpans6.htm#6.1.0580>6.1.0580 &gt;R</a> ,
<A href=dpans6.htm#6.1.2070>6.1.2070 R@</a> ,
<A href=dpans6.htm#6.2.0340>6.2.0340 2&gt;R</a> ,
<A href=dpans6.htm#6.2.0410>6.2.0410 2R&gt;</a> ,
<A href=dpans6.htm#6.2.0415>6.2.0415 2R@</a>
</code>

<P>

<hr>
<A name=6.1.2070>
<code>
6.1.2070 <b>R@</b>
</code>
</a>
<BR>
<B>r-fetch</B>       CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- x ) ( R:  x -- x )
</pre>
<P>

Copy x from
the return stack to the data stack.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<A href=dpans6.htm#6.1.0580>6.1.0580 &gt;R</a> ,
<A href=dpans6.htm#6.1.2060>6.1.2060 R&gt;</a> ,
<A href=dpans6.htm#6.2.0340>6.2.0340 2&gt;R</a> ,
<A href=dpans6.htm#6.2.0410>6.2.0410 2R&gt;</a> ,
<A href=dpans6.htm#6.2.0415>6.2.0415 2R@</a>
</code>

<P>

<hr>
<A name=6.1.2120>
<code>
6.1.2120 <b>RECURSE</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( -- )
</pre>
<P>

Append the execution semantics of the current definition to the current
definition. An ambiguous condition exists if RECURSE appears in a
definition after 
<a href=dpans6.htm#6.1.1250>DOES&gt;</a>.

<P>

<code>
See:
<A href=dpans6.htm#6.1.2120>6.1.2120 RECURSE</a> ,
<a href=dpansa6.htm#A.6.1.2120>A.6.1.2120 RECURSE</a>
</code>

<P>

<hr>
<A name=6.1.2140>
<code>
6.1.2140 <b>REPEAT</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: orig dest -- )
</pre>
<P>

Append the run-time semantics given below to the current definition,
resolving the backward reference dest. Resolve the forward reference
orig using the location following the appended run-time semantics.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue execution
at the location given by dest.

<P>

<code>
See:
<A href=dpans6.htm#6.1.0760>6.1.0760 BEGIN</a> ,
<A href=dpans6.htm#6.1.2430>6.1.2430 WHILE</a> ,
<a href=dpansa6.htm#A.6.1.2140>A.6.1.2140 REPEAT</a>
</code>


<P>

<hr>
<A name=6.1.2160>
<code>
6.1.2160 <b>ROT</b>
</code>
</a>
<BR>
<B>rote</B>  CORE
<BR>
<pre>
	( x1 x2 x3 -- x2 x3 x1 )
</pre>

<P>

Rotate the
top three stack entries.


<P>

<hr>
<A name=6.1.2162>
<code>
6.1.2162 <b>RSHIFT</b>
</code>
</a>
<BR>
<B>r-shift</B>       CORE
<BR>
<pre>
	( x1 u -- x2 )
</pre>

<P>

Perform a logical right shift of u bit-places on x1, giving x2. Put
zeroes into the most significant bits vacated by the shift. An
ambiguous condition exists if u is greater than or equal to the number
of bits in a cell.

<P>

<hr>
<A name=6.1.2165>
<code>
6.1.2165 <b>S"</b>
</code>
</a>
<BR>
<B>s-quote</B>       CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"ccc&lt;quote&gt;"</B> -- )
</pre>
<P>

Parse ccc delimited by " (double-quote). Append the run-time semantics
given below to the current definition.


<PRE>
        Run-time: ( -- c-addr u )
</PRE>

<P>

Return c-addr and u describing a string consisting of the characters
ccc. A program shall not alter the returned string.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.2.0855>6.2.0855 C"</a> ,
<A href=dpans11.htm#11.6.1.2165>11.6.1.2165 S"</a> ,
<a href=dpansa6.htm#A.6.1.2165>A.6.1.2165 S"</a>
</code>

<P>

<hr>
<A name=6.1.2170>
<code>
6.1.2170 <b>S&gt;D</b>
</code>
</a>
<BR>
<B>s-to-d</B>        CORE
<BR>
<pre>
	( n -- d )
</pre>

<P>

Convert the
number n to the double-cell number d with the same numerical
value.

<P>

<hr>
<A name=6.1.2210>
<code>
6.1.2210 <b>SIGN</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n -- )
</pre>

<P>

If n is negative, add a minus sign to the beginning of the pictured
numeric output string. An ambiguous condition exists if SIGN executes
outside of a 
<a href=dpans6.htm#6.1.0490>&lt;#</a> 
<a href=dpans6.htm#6.1.0040>#&gt;</a> 
delimited number conversion.

<P>

<hr>
<A name=6.1.2214>
<code>
6.1.2214 <b>SM/REM</b>
</code>
</a>
<BR>
<B>s-m-slash-rem</B> CORE
<BR>
<pre>
	( d1 n1 -- n2 n3 )
</pre>

<P>

Divide d1 by n1, giving the symmetric quotient n3 and the remainder n2.
Input and output stack arguments are signed. An ambiguous condition
exists if n1 is zero or if the quotient lies outside the range of a
single-cell signed integer.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division,
<A href=dpans6.htm#6.1.1561>6.1.1561 FM/MOD</a> ,
<A href=dpans6.htm#6.1.2370>6.1.2370 UM/MOD</a> ,
<a href=dpansa6.htm#A.6.1.2214>A.6.1.2214 SM/REM</a>
</code>

<P>

<hr>
<A name=6.1.2216>
<code>
6.1.2216 <b>SOURCE</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- c-addr u )
</pre>

<P>

c-addr is the address of, and u is the number of characters in, the
input buffer.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.2216>A.6.1.2216 SOURCE</a> ,
<a href=a0006.htm>RFI 0006</a> Writing to Input Buffers.
</code>
<p>

<hr>
<A name=6.1.2220>
<code>
6.1.2220 <b>SPACE</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- )
</pre>

<P>

Display one
space.

<P>

<hr>
<A name=6.1.2230>
<code>
6.1.2230 <b>SPACES</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( n -- )
</pre>

<P>

If n
is greater than zero, display n spaces.

<P>

<hr>
<A name=6.1.2250>
<code>
6.1.2250 <b>STATE</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr is the address of a cell containing the compilation-state flag.
STATE is true when in compilation state, false otherwise. The true
value in STATE is non-zero, but is otherwise implementation-defined.
Only the following standard words alter the value in STATE: : 
(<a href=dpans6.htm#6.1.0450>colon</a>), ;
(<a href=dpans6.htm#6.1.0460>semicolon</a>), 
<a href=dpans6.htm#6.1.0670>ABORT</a>, 
<a href=dpans6.htm#6.1.2050>QUIT</a>, 
<a href=dpans6.htm#6.2.0455>:NONAME</a>, [ 
(<a href=dpans6.htm#6.1.2500>left-bracket</a>), and ]
(<a href=dpans6.htm#6.1.2540>right-bracket</a>).
<p>

<b>Note:</b>  A program shall not directly alter the contents of
STATE.


<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans15.htm#15.6.2.2250>15.6.2.2250 STATE</a> ,
<a href=dpansa6.htm#A.6.1.2250>A.6.1.2250 STATE</a> ,
<a href=a0007.htm>RFI 0007</a> Distinction between <em>immediacy</em> and <em>special compilation semantics</em>.
</code>

<P>

<hr>
<A name=6.1.2260>
<code>
6.1.2260 <b>SWAP</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( x1 x2 -- x2 x1 )
</pre>

<P>

Exchange the
top two stack items.

<P>

<hr>
<A name=6.1.2270>
<code>
6.1.2270 <b>THEN</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: orig -- )
</pre>
<P>

Append the run-time semantics given below to the current definition.
Resolve the forward reference orig using the location of the appended
run-time semantics.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue
execution.

<P>

<code>
See:
<A href=dpans6.htm#6.1.1310>6.1.1310 ELSE</a> ,
<A href=dpans6.htm#6.1.1700>6.1.1700 IF</a> ,
<a href=dpansa6.htm#A.6.1.2270>A.6.1.2270 THEN</a>
</code>

<P>

<hr>
<A name=6.1.2310>
<code>
6.1.2310 <b>TYPE</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( c-addr u -- )
</pre>

<P>

If u is greater than zero, display the character string specified by
c-addr and u.

<P>

When passed a character in a character string whose character-defining
bits have a value between hex 20 and 7E inclusive, the corresponding
standard character, specified by 
<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> graphic characters, is
displayed. Because different output devices can respond differently to
control characters, programs that use control characters to perform
specific functions have an environmental dependency.

<P>

<code>
See:
<A href=dpans6.htm#6.1.1320>6.1.1320 EMIT</a>
</code>

<P>

<hr>
<A name=6.1.2320>
<code>
6.1.2320 <b>U.</b>
</code>
</a>
<BR>
<B>u-dot</B> CORE
<BR>
<pre>
	( u -- )
</pre>

<P>

Display u
in free field format.

<P>

<hr>
<A name=6.1.2340>
<code>
6.1.2340 <b>U&lt;</b>
</code>
</a>
<BR>
<B>u-less-than</B>   CORE
<BR>
<pre>
	( u1 u2 -- flag )
</pre>

<P>

flag is
true if and only if u1 is less than u2.

<P>

<code>
See:
<A href=dpans6.htm#6.1.0480>6.1.0480 &lt;</a>
</code>

<P>

<hr>
<A name=6.1.2360>
<code>
6.1.2360 <b>UM*</b>
</code>
</a>
<BR>
<B>u-m-star</B>      CORE
<BR>
<pre>
	( u1 u2 -- ud )
</pre>

<P>

Multiply u1 by u2, giving the unsigned double-cell product ud. All
values and arithmetic are unsigned.

<P>

<hr>
<A name=6.1.2370>
<code>
6.1.2370 <b>UM/MOD</b>
</code>
</a>
<BR>
<B>u-m-slash-mod</B> CORE
<BR>
<pre>
	( ud u1 -- u2 u3 )
</pre>

<P>

Divide ud by u1, giving the quotient u3 and the remainder u2. All
values and arithmetic are unsigned. An ambiguous condition exists if u1
is zero or if the quotient lies outside the range of a single-cell
unsigned integer.

<P>

<code>
See:
<A href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division,
<A href=dpans6.htm#6.1.1561>6.1.1561 FM/MOD</a> ,
<A href=dpans6.htm#6.1.2214>6.1.2214 SM/REM</a>
</code>

<P>

<hr>
<A name=6.1.2380>
<code>
6.1.2380 <b>UNLOOP</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- ) ( R: loop-sys -- )
</pre>
<P>

Discard the loop-control parameters for the current nesting level. An
UNLOOP is required for each nesting level before the definition may be
<a href=dpans6.htm#6.1.1380>EXIT</a>ed. 
An ambiguous condition exists if the loop-control parameters
are unavailable.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<a href=dpansa6.htm#A.6.1.2380>A.6.1.2380 UNLOOP</a>
</code>

<P>

<hr>
<A name=6.1.2390>
<code>
6.1.2390 <b>UNTIL</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: dest -- )
</pre>
<P>

Append the run-time semantics given below to the current definition,
resolving the backward reference dest.

<P>
<pre>
	Run-time: ( x -- )
</pre>
<P>

If all bits of x are zero, continue execution at the location specified
by dest.

<P>

<code>
See:
<A href=dpans6.htm#6.1.0760>6.1.0760 BEGIN</a> ,
<a href=dpansa6.htm#A.6.1.2390>A.6.1.2390 UNTIL</a>
</code>

<P>

<hr>
<A name=6.1.2410>
<code>
6.1.2410 <b>VARIABLE</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading space delimiters. Parse name delimited by a space. Create
a definition for name with the execution semantics defined below.
Reserve one cell of data space at an aligned address.

<P>

name is referred
to as a <B>variable</B>.

<P>
<pre>
	<i>name</i> Execution: ( -- a-addr )
</pre>
<P>

a-addr is the address of the reserved cell. A program is responsible
for initializing the contents of the reserved cell.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa6.htm#A.6.1.2410>A.6.1.2410 VARIABLE</a>
</code>

<P>

<hr>
<A name=6.1.2430>
<code>
6.1.2430 <b>WHILE</b>
</code>
</a>
<BR>
CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: dest -- orig dest )
</pre>
<P>

Put the location of a new unresolved forward reference orig onto the
control flow stack, under the existing dest. Append the run-time
semantics given below to the current definition. The semantics are
incomplete until orig and dest are resolved (e.g., by 
<a href=dpans6.htm#6.1.2140>REPEAT</a>).

<P>
<pre>
	Run-time: ( x -- )
</pre>
<P>

If all bits of x are zero, continue execution at the location specified
by the resolution of orig.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.2430>A.6.1.2430 WHILE</a>
</code>
<p>

<hr>
<A name=6.1.2450>
<code>
6.1.2450 <b>WORD</b>
</code>
</a>
<BR>
CORE
<BR>
<pre>
	( char <B>"&lt;chars&gt;ccc&lt;char&gt;"</B> -- c-addr )
</pre>

<P>

Skip leading delimiters. Parse characters ccc delimited by char. An
ambiguous condition exists if the length of the parsed string is greater
than the implementation-defined length of a counted string.

<P>

c-addr is the address of a transient region containing the parsed word
as a counted string. If the parse area was empty or contained no
characters other than the delimiter, the resulting string has a zero
length. A space, not included in the length, follows the string. A
program may replace characters within the string.

<P>

<b>Note:</b>  The requirement to follow the string with a space is
obsolescent and is included as a concession to existing programs that
use 
<a href=dpans6.htm#6.2.0970>CONVERT</a>. 
A program shall not depend on the existence of the
space.


<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions,
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpans6.htm#6.2.2008>6.2.2008 PARSE</a> ,
<a href=dpansa6.htm#A.6.1.2450>A.6.1.2450 WORD</a>
</code>

<P>

<hr>
<A name=6.1.2490>
<code>
6.1.2490 <b>XOR</b>
</code>
</a>
<BR>
<B>x-or</B>  CORE
<BR>
<pre>
	( x1 x2 -- x3 )
</pre>

<P>

x3 is
the bit-by-bit exclusive-or of x1 with x2.

<P>

<hr>
<A name=6.1.2500>
<code>
6.1.2500 <b>[</b>
</code>
</a>
<BR>
<B>left-bracket</B> CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
	Execution: ( -- )
</pre>
<P>

Enter interpretation
state. [ is an immediate word.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans3.htm#3.4.5>3.4.5</a> Compilation,
<A href=dpans6.htm#6.1.2540>6.1.2540 ]</a> ,
<a href=dpansa6.htm#A.6.1.2500>A.6.1.2500 [</a>
</code>

<P>

<hr>
<A name=6.1.2510>
<code>
6.1.2510 <b>[']</b>
</code>
</a>
<BR>
<B>bracket-tick</B>  CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters. Parse name delimited by a space. Find
name. Append the run-time semantics given below to the current
definition.

<P>

An ambiguous condition
exists if name is not found.

<P>
<pre>
	Run-time: ( -- xt )
</pre>
<P>

Place name's execution token xt on the stack. The execution token
returned by the compiled phrase 
<b><code>['] X</code></b> is the same value returned
by <b><code>' X</code></b> outside of compilation state.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.1.0070>6.1.0070 '</a> ,
<A href=dpansa6.htm#A.6.1.2033>A.6.1.2033 POSTPONE</a> ,
<a href=dpansa6.htm#A.6.1.2510>A.6.1.2510 [']</a> ,
<A href=dpansd.htm#D.6.7>D.6.7</a> Immediacy.
</code>

<P>

<hr>
<A name=6.1.2520>
<code>
6.1.2520 <b>[CHAR]</b>
</code>
</a>
<BR>
<B>bracket-char</B>  CORE
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters. Parse name delimited by a space. Append the
run-time semantics given below to the current definition.

<P>
<pre>
	Run-time: ( -- char )
</pre>
<P>

Place char, the
value of the first character of name, on the stack.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.1.0895>6.1.0895 CHAR</a> ,
<a href=dpansa6.htm#A.6.1.2520>A.6.1.2520 [CHAR]</a>
</code>

<P>

<hr>
<A name=6.1.2540>
<code>
6.1.2540 <b>]</b>
</code>
</a>
<BR>
<B>right-bracket</B>  CORE
<BR>
<pre>
	( -- )
</pre>

<P>

Enter compilation
state.

<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter,
<A href=dpans3.htm#3.4.5>3.4.5</a> Compilation,
<A href=dpans6.htm#6.1.2500>6.1.2500 [</a> ,
<a href=dpansa6.htm#A.6.1.2540>A.6.1.2540 ]</a> ,
</code>


<hr>
<a name=6.2>
<H2>6.2 Core extension words</H2>
</a>

<p>
<code>
See:
<a href=dpansa6.htm#A.6.2>A.6.2</a> Core extension words
</code>
<p>

<hr>
<A name=6.2.0060>
<code>
6.2.0060 <b>#TIB</b>
</code>
</a>
<BR>
<B>number-t-i-b</B>  CORE EXT
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr
is the address of a cell containing the number of characters in the
terminal input buffer.

<P>

<b>Note:</b>  This word is obsolescent and is included as a concession to
existing implementations.


<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.0060>A.6.2.0060 #TIB</a>
</code>
<p>

<hr>
<A name=6.2.0200>
<code>
6.2.0200 <b>.(</b>
</code>
</a>
<BR>
<B>dot-paren</B>    CORE EXT
<BR>

<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
	Execution: ( <B>"ccc&lt;paren&gt;"</B> -- )
</pre>
<P>

Parse and display ccc delimited by ) (right parenthesis). .( is an
immediate word.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.1.0190>6.1.0190 ."</a> ,
<a href=dpansa6.htm#A.6.2.0200>A.6.2.0200 .(</a>
</code>

<P>

<hr>
<A name=6.2.0210>
<code>
6.2.0210 <b>.R</b>
</code>
</a>
<BR>
<B>dot-r</B> CORE EXT
<BR>
<pre>
	( n1 n2 -- )
</pre>

<P>

Display n1 right aligned in a field n2 characters wide. If the number
of characters required to display n1 is greater than n2, all digits are
displayed with no leading spaces in a field as wide as necessary.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.0210>A.6.2.0210 .R</a>
</code>
<p>

<hr>
<A name=6.2.0260>
<code>
6.2.0260 <b>0&lt;&gt;</b>
</code>
</a>
<BR>
<B>zero-not-equals</B>       CORE EXT
<BR>
<pre>
	( x -- flag )
</pre>

<P>

flag is
true if and only if x is not equal to zero.

<P>

<hr>
<A name=6.2.0280>
<code>
6.2.0280 <b>0&gt;</b>
</code>
</a>
<BR>
<B>zero-greater</B>  CORE EXT
<BR>
<pre>
	( n -- flag )
</pre>

<P>

flag is
true if and only if n is greater than zero.

<P>

<hr>
<A name=6.2.0340>
<code>
6.2.0340 <b>2&gt;R</b>
</code>
</a>
<BR>
<B>two-to-r</B>      CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( x1 x2 -- ) ( R:  -- x1 x2 )
</pre>
<P>

Transfer cell pair x1 x2 to the return stack. Semantically equivalent
to 
<b><code>
SWAP &gt;R &gt;R
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<A href=dpans6.htm#6.1.0580>6.1.0580 &gt;R</a> ,
<A href=dpans6.htm#6.1.2060>6.1.2060 R&gt;</a> ,
<A href=dpans6.htm#6.1.2070>6.1.2070 R@</a> ,
<A href=dpans6.htm#6.2.0410>6.2.0410 2R&gt;</a> ,
<A href=dpans6.htm#6.2.0415>6.2.0415 2R@</a> ,
<a href=dpansa6.htm#A.6.2.0340>A.6.2.0340 2&gt;R</a>
</code>

<P>

<hr>
<A name=6.2.0410>
<code>
6.2.0410 <b>2R&gt;</b>
</code>
</a>
<BR>
<B>two-r-from</B>    CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- x1 x2 ) ( R:  x1 x2 -- )
</pre>
<P>

Transfer cell pair x1 x2 from the return stack. Semantically equivalent
to 
<b><code>
R&gt; R&gt; SWAP
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<A href=dpans6.htm#6.1.0580>6.1.0580 &gt;R</a> ,
<A href=dpans6.htm#6.1.2060>6.1.2060 R&gt;</a> ,
<A href=dpans6.htm#6.1.2070>6.1.2070 R@</a> ,
<A href=dpans6.htm#6.2.0340>6.2.0340 2&gt;R</a> ,
<A href=dpans6.htm#6.2.0415>6.2.0415 2R@</a> ,
<a href=dpansa6.htm#A.6.2.0410>A.6.2.0410 2R&gt;</a>
</code>

<P>

<hr>
<A name=6.2.0415>
<code>
6.2.0415 <b>2R@</b>
</code>
</a>
<BR>
<B>two-r-fetch</B>   CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( -- x1 x2 ) ( R:  x1 x2 -- x1 x2 )
</pre>
<P>

Copy cell pair x1 x2 from the return stack. Semantically equivalent to
<b><code>
R&gt; R&gt; 2DUP &gt;R &gt;R SWAP
</code></b>.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.3>3.2.3.3</a> Return stack,
<A href=dpans6.htm#6.1.0580>6.1.0580 &gt;R</a> ,
<A href=dpans6.htm#6.1.2060>6.1.2060 R&gt;</a> ,
<A href=dpans6.htm#6.1.2070>6.1.2070 R@</a> ,
<A href=dpans6.htm#6.2.0340>6.2.0340 2&gt;R</a> ,
<A href=dpans6.htm#6.2.0410>6.2.0410 2R&gt;</a>
</code>

<P>

<hr>
<A name=6.2.0455>
<code>
6.2.0455 <b>:NONAME</b>
</code>
</a>
<BR>
<B>colon-no-name</B> CORE EXT
<BR>
<pre>
	( C:  -- colon-sys )  ( S:  -- xt )
</pre>

<P>

Create an execution token xt, enter compilation state and start the
current definition, producing colon-sys. Append the initiation
semantics given below to the current definition.

<P>

The execution semantics of xt will be determined by the words compiled
into the body of the definition. This definition can be executed later
by using xt 
<a href=dpans6.htm#6.1.1370>EXECUTE</a>.

<P>

If the control-flow stack is implemented using the data stack, colon-sys
shall be the topmost item on the data stack.

<p>

<pre>
	Initiation: ( i*x -- i*x ) ( R:  -- nest-sys )
</pre>
<P>

Save implementation-dependent information nest-sys about the calling
definition. The stack effects i*x represent arguments to xt.

<P>
<pre>
	<i>xt</i> Execution: ( i*x -- j*x )
</pre>
<P>

Execute the definition specified by xt. The stack effects i*x and j*x
represent arguments to and results from xt, respectively.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.0455>A.6.2.0455 :NONAME</a> ,
<A href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control-flow stack.
</code>
<p>

<hr>
<A name=6.2.0500>
<code>
6.2.0500 <b>&lt;&gt;</b>
</code>
</a>
<BR>
<B>not-equals</B>    CORE EXT
<BR>
<pre>
	( x1 x2 -- flag )
</pre>

<P>

flag is
true if and only if x1 is not bit-for-bit the same as x2.

<P>

<hr>
<A name=6.2.0620>
<code>
6.2.0620 <b>?DO</b>
</code>
</a>
<BR>
<B>question-do</B>   CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: -- do-sys )
</pre>
<P>

Put do-sys onto the control-flow stack. Append the run-time semantics
given below to the current definition. The semantics are incomplete
until resolved by a consumer of do-sys such as 
<a href=dpans6.htm#6.1.1800>LOOP</a>.
<P>
<pre>
	Run-time: ( n1|u1 n2|u2 -- ) ( R: --  | loop-sys )
</pre>
<P>

If n1|u1 is equal to n2|u2, continue execution at the location given by
the consumer of do-sys. Otherwise set up loop control parameters with
index n2|u2 and limit n1|u1 and continue executing immediately following
?DO. Anything already on the return stack becomes unavailable until the
loop control parameters are discarded. An ambiguous condition exists if
n1|u1 and n2|u2 are not both of the same type.

<P>

<code>
See:
<A href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control-flow stack,
<A href=dpans6.htm#6.1.0140>6.1.0140 +LOOP</a> ,
<A href=dpans6.htm#6.1.1240>6.1.1240 DO</a> ,
<A href=dpans6.htm#6.1.1680>6.1.1680 I</a> ,
<A href=dpans6.htm#6.1.1760>6.1.1760 LEAVE</a> ,
<A href=dpans6.htm#6.1.2380>6.1.2380 UNLOOP</a> ,
<a href=dpansa6.htm#A.6.2.0620>A.6.2.0620 ?DO</a>
</code>

<P>

<hr>
<A name=6.2.0700>
<code>
6.2.0700 <b>AGAIN</b>
</code>
</a>
<BR>
CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: dest -- )
</pre>
<P>

Append the run-time semantics given below to the current definition,
resolving the backward reference dest.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue execution at the location specified by dest. If no other
control flow words are used, any program code after AGAIN will not be
executed.

<p>
<code>
See:
<A href=dpans6.htm#6.1.0760>6.1.0760 BEGIN</a> ,
<a href=dpansa6.htm#A.6.2.0700>A.6.2.0700 AGAIN</a>
</code>

<P>

<hr>
<A name=6.2.0855>
<code>
6.2.0855 <b>C"</b>
</code>
</a>
<BR>
<B>c-quote</B>       CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"ccc&lt;quote&gt;"</B> -- )
</pre>
<P>

Parse ccc delimited by " (double-quote) and append the run-time
semantics given below to the current definition.

<P>
<pre>
	Run-time: ( -- c-addr )
</pre>
<P>

Return c-addr, a counted string consisting of the characters ccc. A
program shall not alter the returned string.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.1.2165>6.1.2165 S"</a> ,
<A href=dpans11.htm#11.6.1.2165>11.6.1.2165 S"</a> ,
<a href=dpansa6.htm#A.6.2.0855>A.6.2.0855 C"</a>
</code>

<P>

<hr>
<A name=6.2.0873>
<code>
6.2.0873 <b>CASE</b>
</code>
</a>
<BR>
CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: -- case-sys )
</pre>
<P>

Mark the start of the CASE ... 
<a href=dpans6.htm#6.2.1950>OF</a> ... 
<a href=dpans6.htm#6.2.1343>ENDOF</a> ... 
<a href=dpans6.htm#6.2.1342>ENDCASE</a> structure.
Append the run-time semantics given below to the current definition.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue
execution.

<P>

<code>
See:
<a href=dpansa6.htm#A.6.2.0873>A.6.2.0873 CASE</a>
</code>

<P>

<hr>
<A name=6.2.0945>
<code>
6.2.0945 <b>COMPILE,</b>
</code>
</a>
<BR>
<B>compile-comma</B> CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Execution: ( xt -- )
</pre>
<P>

Append the execution semantics of the definition represented by xt to
the execution semantics of the current definition.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.0945>A.6.2.0945 COMPILE,</a>
</code>
<p>

<hr>
<A name=6.2.0970>
<code>
6.2.0970 <b>CONVERT</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( ud1 c-addr1 -- ud2 c-addr2 )
</pre>

<P>

ud2 is the result of converting the characters within the text beginning
at the first character after c-addr1 into digits, using the number in
<a href=dpans6.htm#6.1.0750>BASE</a>, 
and adding each digit to ud1 after multiplying ud1 by the number
in BASE. Conversion continues until a character that is not convertible
is encountered. c-addr2 is the location of the first unconverted
character. An ambiguous condition exists if ud2 overflows.

<P>

<b>Note:</b>  This word is obsolescent and is included as a concession to
existing implementations. Its function is superseded by 
<a href=dpans6.htm#6.1.0570>6.1.0570</a>
&gt;NUMBER.

<P>

<code>
See:
<A href=dpans3.htm#3.2.1.2>3.2.1.2</a> Digit conversion,
<a href=dpansa6.htm#A.6.2.0970>A.6.2.0970 CONVERT</a>
</code>

<P>

<hr>
<A name=6.2.1342>
<code>
6.2.1342 <b>ENDCASE</b>
</code>
</a>
<BR>
<B>end-case</B>      CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: case-sys -- )
</pre>
<P>

Mark the end of the 
<a href=dpans6.htm#6.2.0873>CASE</a> ... 
<a href=dpans6.htm#6.2.1950>OF</a> ... 
<a href=dpans6.htm#6.2.1343>ENDOF</a> 
... ENDCASE structure. Use
case-sys to resolve the entire structure. Append the run-time semantics
given below to the current definition.

<P>
<pre>
	Run-time: ( x -- )
</pre>
<P>

Discard the
case selector x and continue execution.

<P>

<code>
See:
<a href=dpansa6.htm#A.6.2.1342>A.6.2.1342 ENDCASE</a>
</code>

<P>

<hr>
<A name=6.2.1343>
<code>
6.2.1343 <b>ENDOF</b>
</code>
</a>
<BR>
<B>end-of</B>        CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: case-sys1 of-sys -- case-sys2 )
</pre>
<P>

Mark the end of the 
<a href=dpans6.htm#6.2.1950>OF</a> 
... ENDOF part of the 
<a href=dpans6.htm#6.2.0873>CASE</a> 
structure. The next
location for a transfer of control resolves the reference given by
of-sys. Append the run-time semantics given below to the current
definition. Replace case-sys1 with case-sys2 on the control-flow stack,
to be resolved by 
<a href=dpans6.htm#6.2.1342>ENDCASE</a>.

<P>
<pre>
	Run-time: ( -- )
</pre>
<P>

Continue execution at
the location specified by the consumer of case-sys2.

<P>

<code>
See:
<a href=dpansa6.htm#A.6.2.1343>A.6.2.1343 ENDOF</a>
</code>

<P>

<hr>
<A name=6.2.1350>
<code>
6.2.1350 <b>ERASE</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( addr u -- )
</pre>

<P>

If u
is greater than zero, clear all bits in each of u consecutive address
units of memory beginning at addr .

<P>

<hr>
<A name=6.2.1390>
<code>
6.2.1390 <b>EXPECT</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( c-addr +n -- )
</pre>

<P>

Receive a string of at most +n characters. Display graphic characters
as they are received. A program that depends on the presence or absence
of non-graphic characters in the string has an environmental dependency.
The editing functions, if any, that the system performs in order to
construct the string of characters are implementation-defined.

<P>

Input terminates when an implementation-defined line terminator is
received or when the string is +n characters long. When input
terminates, nothing is appended to the string and the display is
maintained in an implementation-defined way.

<P>

Store the
string at c-addr and its length in 
<a href=dpans6.htm#6.2.2240>SPAN</a>.

<P>

<b>Note:</b>  This word is obsolescent and is included as a concession to
existing implementations. Its function is superseded by 
<a href=dpans6.htm#6.1.0695>6.1.0695</a>
ACCEPT.


<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.1390>A.6.2.1390 EXPECT</a>
</code>
<p>

<hr>
<A name=6.2.1485>
<code>
6.2.1485 <b>FALSE</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- false )
</pre>

<P>

Return a
false flag.

<P>

<code>
See:
<A href=dpans3.htm#3.1.3.1>3.1.3.1</a> Flags
</code>

<P>

<hr>
<A name=6.2.1660>
<code>
6.2.1660 <b>HEX</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- )
</pre>

<P>

Set contents
of 
<a href=dpans6.htm#6.1.0750>BASE</a> 
to sixteen.


<P>

<hr>
<A name=6.2.1850>
<code>
6.2.1850 <b>MARKER</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading space delimiters. Parse name delimited by a space. Create
a definition for name with the execution semantics defined below.

<P>
<pre>
	<i>name</i> Execution: ( -- )
</pre>
<P>

Restore all dictionary allocation and search order pointers to the state
they had just prior to the definition of name. Remove the definition of
name and all subsequent definitions. Restoration of any structures
still existing that could refer to deleted definitions or deallocated
data space is not necessarily provided. No other contextual information
such as numeric base is affected.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans15.htm#15.6.2.1580>15.6.2.1580 FORGET</a> ,
<a href=dpansa6.htm#A.6.2.1850>A.6.2.1850 MARKER</a>
</code>


<P>

<hr>
<A name=6.2.1930>
<code>
6.2.1930 <b>NIP</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( x1 x2 -- x2 )
</pre>

<P>

Drop the
first item below the top of stack.


<P>

<hr>
<A name=6.2.1950>
<code>
6.2.1950 <b>OF</b>
</code>
</a>
<BR>
CORE EXT
<BR>

<P>
<pre>
	Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( C: -- of-sys )
</pre>
<P>

Put of-sys onto the control flow stack. Append the run-time semantics
given below to the current definition. The semantics are incomplete
until resolved by a consumer of of-sys such as 
<a href=dpans6.htm#6.2.1343>ENDOF</a>.

<P>
<pre>
	Run-time: ( x1 x2 --   | x1 )
</pre>
<P>

If the two values on the stack are not equal, discard the top value and
continue execution at the location specified by the consumer of of-sys,
e.g., following the next ENDOF. Otherwise, discard both values and
continue execution in line.

<P>

<code>
See:
<A href=dpans6.htm#6.2.0873>6.2.0873 CASE</a> ,
<A href=dpans6.htm#6.2.1342>6.2.1342 ENDCASE</a> ,
<a href=dpansa6.htm#A.6.2.1950>A.6.2.1950 OF</a>
</code>

<P>

<hr>
<A name=6.2.2000>
<code>
6.2.2000 <b>PAD</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- c-addr )
</pre>

<P>

c-addr is the address of a transient region that can be used to hold
data for intermediate processing.

<P>

<code>
See:
<A href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions,
<a href=dpansa6.htm#A.6.2.2000>A.6.2.2000 PAD</a>
</code>

<P>

<hr>
<A name=6.2.2008>
<code>
6.2.2008 <b>PARSE</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( char <B>"ccc&lt;char&gt;"</B> -- c-addr u )
</pre>

<P>

Parse ccc
delimited by the delimiter char.

<P>

c-addr is the address (within the input buffer) and u is the length of
the parsed string. If the parse area was empty, the resulting string
has a zero length.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa6.htm#A.6.2.2008>A.6.2.2008 PARSE</a>
</code>


<P>

<hr>
<A name=6.2.2030>
<code>
6.2.2030 <b>PICK</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( xu ... x1 x0 u -- xu ... x1 x0 xu )
</pre>

<P>

Remove u.
Copy the xu to the top of the stack. An ambiguous condition exists
if there are less than u+2 items on the stack before PICK is executed.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.2030>A.6.2.2030 PICK</a>
</code>
<p>

<hr>
<A name=6.2.2040>
<code>
6.2.2040 <b>QUERY</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- )
</pre>

<P>

Make the user input device the input source. Receive input into the
terminal input buffer, replacing any previous contents. Make the
result, whose address is returned by 
<a href=dpans6.htm#6.2.2290>TIB</a>, 
the input buffer. Set 
<a href=dpans6.htm#6.1.0560>&gt;IN</a>
to zero.

<P>

<b>Note:</b>  This word is obsolescent and is included as a concession to
existing implementations.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.2040>A.6.2.2040 QUERY</a> ,
<a href=a0006.htm>RFI 0006</a>.
</code>
<p>

<hr>
<A name=6.2.2125>
<code>
6.2.2125 <b>REFILL</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- flag )
</pre>

<P>

Attempt to fill the input buffer from the input source, returning a true
flag if successful.

<P>

When the input source is the user input device, attempt to receive input
into the terminal input buffer. If successful, make the result the
input buffer, set 
<a href=dpans6.htm#6.1.0560>&gt;IN</a> 
to zero, and return true. Receipt of a line
containing no characters is considered successful. If there is no input
available from the current input source, return false.

<P>

When the input source is a string from 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>, 
return false and
perform no other action.

<P>

<code>
See:
<A href=dpans7.htm#7.6.2.2125>7.6.2.2125 REFILL</a> ,
<A href=dpans11.htm#11.6.2.2125>11.6.2.2125 REFILL</a> ,
<a href=dpansa6.htm#A.6.2.2125>A.6.2.2125 REFILL</a>
</code>

<P>

<hr>
<A name=6.2.2148>
<code>
6.2.2148 <b>RESTORE-INPUT</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( xn ... x1 n -- flag )
</pre>

<P>

Attempt to restore the input source specification to the state described
by x1 through xn. flag is true if the input source specification cannot
be so restored.

<P>

An ambiguous condition exists if the input source represented by the
arguments is not the same as the current input source.

<P>

<code>
See:
<A href=dpansa6.htm#A.6.2.2182>A.6.2.2182 SAVE-INPUT</a>
</code>

<P>

<hr>
<A name=6.2.2150>
<code>
6.2.2150 <b>ROLL</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( xu xu-1 ... x0 u -- xu-1 ... x0 xu )
</pre>

<P>

Remove u. Rotate u+1 items on the top of the stack. An ambiguous
condition exists if there are less than u+2 items on the stack before
ROLL is executed.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.2150>A.6.2.2150 ROLL</a>
</code>
<p>

<hr>
<A name=6.2.2182>
<code>
6.2.2182 <b>SAVE-INPUT</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- xn ... x1 n )
</pre>

<P>

x1 through xn describe the current state of the input source
specification for later use by 
<a href=dpans6.htm#6.2.2148>RESTORE-INPUT</a>.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.2182>A.6.2.2182 SAVE-INPUT</a>
</code>
<p>

<hr>
<A name=6.2.2218>
<code>
6.2.2218 <b>SOURCE-ID</b>
</code>
</a>
<BR>
<B>source-i-d</B>    CORE EXT
<BR>
<pre>
	( -- 0 | -1 )
</pre>

<P>

Identifies the
input source as follows:

<P>


<PRE>
SOURCE-ID       Input source
-1              String (via <a href=dpans6.htm#6.1.1360>EVALUATE</a>)
 0              User input device
</PRE>

<P>

<code>
See:
<A href=dpans11.htm#11.6.1.2218>11.6.1.2218 SOURCE-ID</a>
</code>

<P>

<hr>
<A name=6.2.2240>
<code>
6.2.2240 <b>SPAN</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr is the address of a cell containing the count of characters
stored by the last execution of 
<a href=dpans6.htm#6.2.1390>EXPECT</a>.

<P>

<b>Note:</b>  This word is obsolescent and is included as a concession to
existing implementations.


<P>

<hr>
<A name=6.2.2290>
<code>
6.2.2290 <b>TIB</b>
</code>
</a>
<BR>
<B>t-i-b</B> CORE EXT
<BR>
<pre>
	( -- c-addr )
</pre>

<P>

c-addr
is the address of the terminal input buffer.

<P>

<b>Note:</b>   This word is obsolescent and is included as a concession to
existing implementations.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.2290>A.6.2.2290 TIB</a> ,
<a href=a0006.htm>RFI 0006</a>.
</code>
<P>

<hr>
<A name=6.2.2295>
<code>
6.2.2295 <b>TO</b>
</code>
</a>
<BR>
CORE EXT
<BR>

<P>

<pre>
	Interpretation: ( x <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading spaces and parse name delimited by a space. Store x in
name. An ambiguous condition exists if name was not defined by 
<a href=dpans6.htm#6.2.2405>VALUE</a>.

<P>
<pre>
	Compilation: ( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading spaces and parse name delimited by a space. Append the
run-time semantics given below to the current definition. An ambiguous
condition exists if name was not defined by VALUE.

<P>
<pre>
	Run-time: ( x -- )
</pre>
<P>

Store x
in name.

<P>

<b>Note:</b>   An ambiguous condition exists if either 
<a href=dpans6.htm#6.1.2033>POSTPONE</a> or 
<a href=dpans6.htm#6.2.2530>[COMPILE]</a>
is applied to TO.

<P>

<code>
See:
<A href=dpans13.htm#13.6.1.2295>13.6.1.2295 TO</a> ,
<a href=dpansa6.htm#A.6.2.2295>A.6.2.2295 TO</a>
</code>

<P>

<hr>
<A name=6.2.2298>
<code>
6.2.2298 <b>TRUE</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- true )
</pre>

<P>

Return a
true flag, a single-cell value with all bits set.

<P>

<code>
See:
<A href=dpans3.htm#3.1.3.1>3.1.3.1</a> Flags,
<a href=dpansa6.htm#A.6.2.2298>A.6.2.2298 TRUE</a>
</code>

<P>

<hr>
<A name=6.2.2300>
<code>
6.2.2300 <b>TUCK</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( x1 x2 -- x2 x1 x2 )
</pre>

<P>

Copy the
first (top) stack item below the second stack item.

<P>

<hr>
<A name=6.2.2330>
<code>
6.2.2330 <b>U.R</b>
</code>
</a>
<BR>
<B>u-dot-r</B>       CORE EXT
<BR>
<pre>
	( u n -- )
</pre>

<P>

Display u right aligned in a field n characters wide. If the number of
characters required to display u is greater than n, all digits are
displayed with no leading spaces in a field as wide as necessary.

<P>

<hr>
<A name=6.2.2350>
<code>
6.2.2350 <b>U&gt;</b>
</code>
</a>
<BR>
<B>u-greater-than</B>        CORE EXT
<BR>
<pre>
	( u1 u2 -- flag )
</pre>

<P>

flag is
true if and only if u1 is greater than u2.

<P>

<code>
See:
<A href=dpans6.htm#6.1.0540>6.1.0540 &gt;</a>
</code>

<P>

<hr>
<A name=6.2.2395>
<code>
6.2.2395 <b>UNUSED</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( -- u )
</pre>

<P>

u is
the amount of space remaining in the region addressed by 
<a href=dpans6.htm#6.1.1650>HERE</a> , in
address units.

<P>

<hr>
<A name=6.2.2405>
<code>
6.2.2405 <b>VALUE</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( x <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading
space delimiters. Parse name delimited by a space. Create a
definition for name with the execution semantics defined below, with an
initial value equal to x.

<P>

name is
referred to as a <B>value</B>.

<P>
<pre>
	<i>name</i> Execution: ( -- x )
</pre>
<P>

Place x on the stack. The value of x is that given when name 
was created,
until the phrase <b><code>x TO name</code></b> 
is executed, causing a new value of x to be
associated with name.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa6.htm#A.6.2.2405>A.6.2.2405 VALUE</a> ,
<a href=dpans6.htm#6.2.2295>6.2.2295 TO</a>
</code>

<P>

<hr>
<A name=6.2.2440>
<code>
6.2.2440 <b>WITHIN</b>
</code>
</a>
<BR>
CORE EXT
<BR>
<pre>
	( n1|u1 n2|u2 n3|u3 -- flag )
</pre>

<P>

Perform a comparison of a test value n1|u1 with a lower limit n2|u2 and
an upper limit n3|u3, returning true if either (n2|u2 &lt; n3|u3 and
(n2|u2 &lt;= n1|u1 and n1|u1 &lt; n3|u3)) or (n2|u2 &gt; n3|u3 and
(n2|u2 &lt;= n1|u1 or n1|u1 &lt; n3|u3)) is true, returning false
otherwise. An ambiguous condition exists if n1|u1, n2|u2, and n3|u3 are
not all the same type.

<P>
<code>
See:
<a href=dpansa6.htm#A.6.2.2440>A.6.2.2440 WITHIN</a>
</code>
<p>

<hr>
<A name=6.2.2530>
<code>
6.2.2530 <b>[COMPILE]</b>
</code>
</a>
<BR>
<B>bracket-compile</B>       CORE EXT
<BR>

<P>
<pre>
	Intrepretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters. Parse name delimited by a space. Find
name. If name has other than default compilation semantics, append them
to the current definition; otherwise append the execution semantics of
name. An ambiguous condition exists if name is not found.

<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpans6.htm#6.1.2033>6.1.2033 POSTPONE</a> ,
<a href=dpansa6.htm#A.6.2.2530>A.6.2.2530 [COMPILE]</a>
</code>

<P>

<hr>
<A name=6.2.2535>
<code>
6.2.2535 <b>\</b>
</code>
</a>
<BR>
<B>backslash</B>  CORE EXT
<BR>

<P>
<pre>
	Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
	Execution: ( <B>"ccc&lt;eol&gt;"</B>-- )
</pre>
<P>

Parse and discard
the remainder of the parse area. \ is an immediate word.

<P>

<code>
See:
<A href=dpans7.htm#7.6.2.2535>7.6.2.2535 \</a> ,
<a href=dpansa6.htm#A.6.2.2535>A.6.2.2535 \</a>
</code>

<P>


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans7.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpans7.htm/     851247120   500   0     100644  14838     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans6.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans8.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=7.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>7. The optional Block word set</H1>

<code>
See:
<a href=dpansa7.htm#A.7>A.7</a> The optional Block word set
</code>

<hr>
<A name=7.1>
<H2>7.1 Introduction</H2>
</a>


<hr>
<A name=7.2>
<H2>7.2 Additional terms</H2>
</a>

<DL><DT><B>block:</B>  <DD>1024 characters of data on mass
storage, designated by a block number.
<DT><B>block buffer:</B> <DD>A block-sized region of data space where a block
is
made temporarily available for use.  The current block buffer is the
block buffer most recently accessed by 
<a href=dpans7.htm#7.6.1.0800>BLOCK</a>, 
<a href=dpans7.htm#7.6.1.0820>BUFFER</a>, 
<a href=dpans7.htm#7.6.1.1790>LOAD</a>, 
<a href=dpans7.htm#7.6.2.1770>LIST</a>, or
<a href=dpans7.htm#7.6.2.2280>THRU</a>.
</DL>

<P>
<code>
See:
<a href=dpansa7.htm#A.7.2>A.7.2</a> Additional terms
</code>

<hr>
<A name=7.3>
<H2>7.3 Additional usage requirements</H2>
</a>


<hr>
<A name=7.3.1>
<H3>7.3.1 Environmental queries</H3>
</a>

Append table 7.1
to table 3.5.
<P>
<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 7.1 - Environmental Query Strings


<PRE>
String          Value data type  Constant?       Meaning
------          ---------------  ---------       -------
BLOCK           flag             no              block word set present
BLOCK-EXT       flag             no              block extensions word set present

</PRE>
<P>

<hr>
<A name=7.3.2>
<H3>7.3.2 Data space</H3>
</a>

A program may access memory
within a valid block buffer.
<P>
<code>
See:
<A href=dpans3.htm#3.3.3>3.3.3</a> Data Space
</code>

<P>

<hr>
<A name=7.3.3>
<H3>7.3.3 Block buffer regions</H3>
</a>

The address of a block buffer returned by 
<a href=dpans7.htm#7.6.1.0800>BLOCK</a> or 
<a href=dpans7.htm#7.6.1.0820>BUFFER</a> is transient.
A call to BLOCK or BUFFER may render a previously-obtained block-buffer
address invalid, as may a call to any word that:
<P>

<UL>
<LI>parses:
<LI>displays characters on the user output device, such as 
<a href=dpans6.htm#6.1.2310>TYPE</a> or 
<a href=dpans6.htm#6.1.1320>EMIT</a>;
<LI>controls the user output device, such as 
<a href=dpans6.htm#6.1.0990>CR</a> or 
<a href=dpans10.htm#10.6.1.0742>AT-XY</a>;
<LI>receives or tests for the presence of characters from the user input
device such as 
<a href=dpans6.htm#6.1.0695>ACCEPT</a> or 
<a href=dpans6.htm#6.1.1750>KEY</a>;
<LI>waits for a condition or event, such as 
<a href=dpans10.htm#10.6.2.1905>MS</a> or 
<a href=dpans10.htm#10.6.2.1305>EKEY</a>;
<LI>manages the block buffers, such as 
<a href=dpans7.htm#7.6.1.1559>FLUSH</a>, 
<a href=dpans7.htm#7.6.1.2180>SAVE-BUFFERS</a>, or
<a href=dpans7.htm#7.6.2.1330>EMPTY-BUFFERS</a>;
<LI>performs any operation on a file or file-name directory that implies
I/O, such as 
<a href=dpans6.htm#6.2.2125>REFILL</a> or any word that returns an ior;
<LI>implicitly performs I/O, such as text interpreter nesting and
un-nesting when files are being used (including un-nesting implied by 
<a href=dpans9.htm#9.6.1.2275>THROW</a>).
</UL>
<P>

If the input source is a block, these restrictions also apply to the address
returned by 
<a href=dpans6.htm#6.1.2216>SOURCE</a>.
<P>

Block buffers are
uniquely assigned to blocks.

<P>


<hr>
<A name=7.3.4>
<H3>7.3.4 Parsing</H3>
</a>

The Block word set implements an alternative input source for the text
interpreter.  When the input source is a block, 
<a href=dpans7.htm#7.6.1.0790>BLK</a> shall contain the
non-zero block number and the input buffer is the 1024-character buffer
containing that block.
<P>

A block is conventionally displayed
as 16 lines of 64 characters.
<P>

A program may switch the input source to a block by using 
<a href=dpans7.htm#7.6.1.1790>LOAD</a> or 
<a href=dpans7.htm#7.6.2.2280>THRU</a>.
Input sources may be nested using LOAD and 
<a href=dpans6.htm#6.1.1360>EVALUATE</a> in any order.
<P>

A program may reposition the parse area within a block by manipulating
<a href=dpans6.htm#6.1.0560>&gt;IN</a>.  
More extensive repositioning can be accomplished using 
<a href=dpans6.htm#6.2.2182>SAVE-INPUT</a>
and 
<a href=dpans6.htm#6.2.2148>RESTORE-INPUT</a>.
<P>
<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing
</code>
<P>


<hr>
<A name=7.3.5>
<H3>7.3.5 Possible action on an ambiguous condition</H3>
</a>
<p>
<UL>
<LI>A system with the Block word set may set interpretation state and interpret
a block.
</UL>

<code>
See:
<A href=dpans3.htm#3.4.4>3.4.4</a> Possible action on an ambiguous
condition
</code>
<P>

<hr>
<A name=7.4>
<H2>7.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=7.4.1>
<H3>7.4.1 System documentation</H3>
</a>


<hr>
<A name=7.4.1.1>
<H4>7.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>the format used for display by 
<a href=dpans7.htm#7.6.2.1770>7.6.2.1770</a> LIST (if implemented);
<LI>the length of a line affected by 
<a href=dpans7.htm#7.6.2.2535>7.6.2.2535</a> \ (if implemented).
</UL>
<P>


<hr>
<A name=7.4.1.2>
<H4>7.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI>Correct block read was not possible;
<LI>I/O exception in block transfer;
<LI>Invalid block number 
(<a href=dpans7.htm#7.6.1.0800>7.6.1.0800</a> BLOCK, 
<a href=dpans7.htm#7.6.1.0820>7.6.1.0820</a> BUFFER, 
<a href=dpans7.htm#7.6.1.1790>7.6.1.1790</a> LOAD);
<LI>A program directly alters the contents of 
<a href=dpans7.htm#7.6.1.0790>7.6.1.0790</a> BLK;
<LI>No current block buffer for 
<a href=dpans7.htm#7.6.1.2400>7.6.1.2400</a> UPDATE.
</UL>

<P>


<hr>
<A name=7.4.1.3>
<H4>7.4.1.3 Other system documentation</H4>
</a>

<UL>
<LI>any restrictions a multiprogramming system places on the use of buffer
addresses;
<LI>the number of blocks available for source text and data.
</UL>
<P>


<hr>
<A name=7.4.2>
<H3>7.4.2 Program documentation</H3>
</a>

<UL>
<LI>the number of blocks required by the program.
</UL>
<P>


<hr>
<A name=7.5>
<H2>7.5 Compliance and labeling</H2>
</a>


<hr>
<A name=7.5.1>
<H3>7.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Block word set</B> shall be appended to the
label of any Standard System that provides all of the Block word set.
<P>

The phrase <B>Providing name(s) from the Block Extensions word set</B>
shall be appended to the label of any Standard System that provides
portions of the Block Extensions word set.
<P>

The phrase <B>Providing the Block Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
Block and Block Extensions word sets.
<P>


<hr>
<A name=7.5.2>
<H3>7.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Block word set</B> shall be appended to the
label of Standard Programs that require the system to provide the Block
word set.
<P>

The phrase <B>Requiring name(s) from the Block Extensions word set</B>
shall be appended to the label of Standard Programs that require the
system to provide portions of the Block Extensions word set.
<P>

The phrase <B>Requiring the Block Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the Block and Block Extensions word sets.
<P>


<hr>
<A name=7.6>
<H2>7.6 Glossary</H2>
</a>


<hr>
<A name=7.6.1>
<H3>7.6.1 Block words</H3>
</a>


<hr>
<A name=7.6.1.0790>
<code>
7.6.1.0790 <b>BLK</b>
</code>
</a>
<BR>
<B>b-l-k</B> BLOCK
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr is the address of a cell containing zero or the number of the
mass-storage block being interpreted.  If BLK contains zero, the input
source is not a block and can be identified by 
<a href=dpans6.htm#6.2.2218>SOURCE-ID</a>, if SOURCE-ID
is available.  An ambiguous condition exists if a program directly
alters the contents of BLK.

<p>
<code>
See:
<A href=dpans7.htm#7.3.3>7.3.3</a> Block buffer regions
</code>
<p>

<hr>
<A name=7.6.1.0800>
<code>
7.6.1.0800 <b>BLOCK</b>
</code>
</a>
<BR>
BLOCK
<BR>
<pre>
	( u -- a-addr )
</pre>

<P>

a-addr is the address of the first character of the block buffer assigned to
mass-storage block u.  An ambiguous condition exists if u is not an available
block number.
<P>

If block u is already in a block buffer, a-addr is the address of that block
buffer.
<P>

If block u is not already in memory and there is an unassigned block buffer,
transfer block u from mass storage to an unassigned block buffer.  a-addr is
the address of that block buffer.
<P>

If block u is not already in memory and there are no unassigned block buffers,
unassign a block buffer.  If the block in that buffer has been 
<a href=dpans7.htm#7.6.1.2400>UPDATE</a>d,
transfer the block to mass storage and transfer block u from mass storage into
that buffer.  a-addr is the address of that block buffer.
<P>

At the conclusion of the operation, the block buffer pointed to by a-addr is
the current block buffer and is assigned to u.

<P>

<hr>
<A name=7.6.1.0820>
<code>
7.6.1.0820 <b>BUFFER</b>
</code>
</a>
<BR>
BLOCK
<BR>
<pre>
	( u -- a-addr )
</pre>

<P>

a-addr is the address of the first character of the block buffer
assigned to block u.  The contents of the block are unspecified.  An
ambiguous condition exists if u is not an available block number.
<P>

If block u is already in a block buffer, a-addr is the address of that
block buffer.
<P>

If block u is not already in memory and there is an unassigned buffer,
a-addr is the address of that block buffer.
<P>

If block u is not already in memory and there are no unassigned block
buffers, unassign a block buffer.  If the block in that buffer has been
<a href=dpans7.htm#7.6.1.2400>UPDATE</a>d, 
transfer the block to mass storage.  a-addr is the address of
that block buffer.
<P>

At the conclusion of the operation, the block buffer pointed to by
a-addr is the current block buffer and is assigned to u.
<P>

<code>
See:    
<A href=dpans7.htm#7.6.1.0800>7.6.1.0800 BLOCK</a>
</code>

<P>

<hr>
<A name=7.6.1.1360>
<code>
7.6.1.1360E <b>EVALUATE</b>
</code>
</a>
<BR>
BLOCK
<BR>
<P>

Extend the semantics of 
<a href=dpans6.htm#6.1.1360>6.1.1360</a> EVALUATE to include:
<P>

	Store zero in BLK.

<P>

<hr>
<A name=7.6.1.1559>
<code>
7.6.1.1559 <b>FLUSH</b>
</code>
</a>
<BR>
BLOCK
<BR>
<pre>
	( -- )
</pre>

<P>

Perform the function of 
<a href=dpans7.htm#7.6.1.2180>SAVE-BUFFERS</a>,
then unassign all block buffers.

<P>

<hr>
<A name=7.6.1.1790>
<code>
7.6.1.1790 <b>LOAD</b>
</code>
</a>
<BR>
BLOCK
<BR>
<pre>
	( i*x u -- j*x )
</pre>

<P>

Save the current input-source specification.  Store u in 
<a href=dpans7.htm#7.6.1.0790>BLK</a> (thus
making block u the input source and setting the input buffer to
encompass its contents), set 
<a href=dpans6.htm#6.1.0560>&gt;IN</a> 
to zero, and interpret.  When the parse
area is exhausted, restore the prior input source specification.  Other
stack effects are due to the words LOADed.
<P>

An ambiguous condition exists if u is zero or is not a valid block
number.
<P>

<code>
See:
<A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter
</code>

<P>

<hr>
<A name=7.6.1.2180>
<code>
7.6.1.2180 <b>SAVE-BUFFERS</b>
</code>
</a>
<BR>
BLOCK
<BR>
<pre>
	( -- )
</pre>

<P>

Transfer the contents of each 
<a href=dpans7.htm#7.6.1.2400>UPDATE</a>d block buffer to mass storage.
Mark all buffers as unmodified.

<P>

<hr>
<A name=7.6.1.2400>
<code>
7.6.1.2400 <b>UPDATE</b>
</code>
</a>
<BR>
BLOCK
<BR>
<pre>
	( -- )
</pre>

<P>

Mark the current block buffer as modified.  An ambiguous condition
exists if there is no current block buffer.
<P>

UPDATE does not immediately cause I/O.
<P>

<code>
See:    
<A href=dpans7.htm#7.6.1.0800>7.6.1.0800 BLOCK</a> ,
<A href=dpans7.htm#7.6.1.0820>7.6.1.0820 BUFFER</a> ,
<A href=dpans7.htm#7.6.1.1559>7.6.1.1559 FLUSH</a> ,
<A href=dpans7.htm#7.6.1.2180>7.6.1.2180 SAVE-BUFFERS</a>
</code>

<P>

<hr>
<A name=7.6.2>
<H3>7.6.2 Block extension words</H3>
</a>

<hr>
<A name=7.6.2.1330>
<code>
7.6.2.1330 <b>EMPTY-BUFFERS</b>
</code>
</a>
<BR>
BLOCK EXT
<BR>
<pre>
	( -- )
</pre>

<P>

Unassign all block buffers.  Do not transfer the contents of any 
<a href=dpans7.htm#7.6.1.2400>UPDATE</a>d
block buffer to mass storage.
<P>

<code>
See:    
<A href=dpans7.htm#7.6.1.0800>7.6.1.0800 BLOCK</a>
</code>

<P>

<hr>
<A name=7.6.2.1770>
<code>
7.6.2.1770 <b>LIST</b>
</code>
</a>
<BR>
BLOCK EXT
<BR>
<pre>
	( u -- )
</pre>

<P>

Display block u in an
implementation-defined format.  Store u in 
<a href=dpans7.htm#7.6.2.2190>SCR</a>.
<P>

<code>
See:    
<A href=dpans7.htm#7.6.1.0800>7.6.1.0800 BLOCK</a>
</code>

<P>

<hr>
<A name=7.6.2.2125>
<code>
7.6.2.2125 <b>REFILL</b>
</code>
</a>
<BR>
BLOCK EXT
<BR>
<pre>
	( -- flag )
</pre>

<P>

Extend the execution semantics of 
<a href=dpans6.htm#6.2.2125>6.2.2125</a> REFILL with the following:
<P>

When the input source is a block, make the next block the input source
and current input buffer by adding one to the value of 
<a href=dpans7.htm#7.6.1.0790>BLK</a> and setting
<a href=dpans6.htm#6.1.0560>&gt;IN</a> to zero.  Return true if the new value of BLK is a valid block
number, otherwise false.
<P>

<code>
See:    
<A href=dpans11.htm#11.6.2.2125>11.6.2.2125 REFILL</a>
</code>

<P>

<hr>
<A name=7.6.2.2190>
<code>
7.6.2.2190 <b>SCR</b>
</code>
</a>
<BR>
<B>s-c-r</B> BLOCK EXT
<BR>
<pre>
	( -- a-addr )
</pre>

<P>

a-addr is the address of a cell containing the block number of the block
most recently 
<a href=dpans7.htm#7.6.2.1770>LIST</a>ed.

<P>
<code>
See:
<a href=dpansa7.htm#A.7.6.2.2190>A.7.6.2.2190 SCR</a>
</code>
<p>

<hr>
<A name=7.6.2.2280>
<code>
7.6.2.2280 <b>THRU</b>
</code>
</a>
<BR>
BLOCK EXT
<BR>
<pre>
	( i*x u1 u2 -- j*x )
</pre>

<P>

<a href=dpans7.htm#7.6.1.1790>LOAD</a> 
the mass storage blocks numbered u1 through u2 in sequence.  Other
stack effects are due to the words LOADed.

<P>

<hr>
<A name=7.6.2.2535>
<code>
7.6.2.2535 <b>\</b>
</code>
</a>
<BR>
<B>backslash</B>     BLOCK EXT
<BR>
<P>

Extend the semantics of 
<a href=dpans6.htm#6.2.2535>6.2.2535</a> \ to be:
<P>
<pre>
        Compilation: Perform the execution semantics given below.
</pre>
<P>
<pre>
        Execution: ( <B>ccc&lt;eol&gt;</B>-- )
</pre>
<P>

If 
<a href=dpans7.htm#7.6.1.0790>BLK</a> 
contains zero, parse and discard the remainder of the parse area;
otherwise parse and discard the portion of the parse area corresponding
to the remainder of the current line.  \ is an immediate word.


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans8.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans8.htm/     851247120   500   0     100644  11358     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans7.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans9.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=8.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>8. The optional Double-Number word set</H1>

<p>
<code>
See:
<a href=dpansa8.htm#A.8>A.8</a> The optional Double-Number word set
</code>

<hr>
<a name=8.1>
<H2>8.1 Introduction</H2>
</a>

Sixteen-bit Forth systems often use double-length numbers.  However,
many Forths on small embedded systems do not, and many users of Forth on
systems with a cell size of 32 bits or more find that the use of
double-length numbers is much diminished.  Therefore, the words that
manipulate double-length entities have been placed in this optional word
set.

<P>

<hr>
<A name=8.2>
<H2>8.2 Additional terms and notation</H2>
</a>

None.

<P>

<hr>
<A name=8.3>
<H2>8.3 Additional usage requirements</H2>
</a>


<hr>
<A name=8.3.1>
<H3>8.3.1 Environmental queries</H3>
</a>

Append table 8.1
to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>

<P>

Table 8.1 - Environmental Query Strings
<P>


<PRE>
String         Value data type   Constant?   Meaning
------         ---------------   ---------   -------
DOUBLE          flag             no          double-number word set present
DOUBLE-EXT      flag             no          double-number extensions word set present
</PRE>

<P>


<hr>
<A name=8.3.2>
<H3>8.3.2 Text interpreter input number conversion</H3>
</a>

When the text interpreter processes a number that is immediately
followed by a decimal point and is not found as a definition name, the
text interpreter shall convert it to a double-cell number.
<P>

For example, entering DECIMAL 1234 leaves the single-cell number 1234 on
the stack, and entering DECIMAL 1234.  leaves the double-cell number
1234 0 on the stack.
<P>

<code>
See:
<A href=dpans3.htm#3.4.1.3>3.4.1.3</a> Text interpreter input number
conversion,
<a href=a0004.htm>RFI 0004</a> Number Conversion.
</code>

<P>

<hr>
<A name=8.4>
<H2>8.4 Additional documentation requirements</H2>
</a>


<hr>
<A name=8.4.1>
<H3>8.4.1 System documentation</H3>
</a>


<hr>
<A name=8.4.1.1>
<H4>8.4.1.1 Implementation-defined options</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>

<hr>
<A name=8.4.1.2>
<H4>8.4.1.2 Ambiguous conditions</H4>
</a>

<UL>
<LI>d outside range of n in 
<a href=dpans8.htm#8.6.1.1140>8.6.1.1140</a> D&gt;S.
</UL>
<P>

<hr>
<A name=8.4.1.3>
<H4>8.4.1.3 Other system documentation</H4>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>


<hr>
<A name=8.4.2>
<H3>8.4.2 Program documentation</H3>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>


<hr>
<A name=8.5>
<H2>8.5 Compliance and labeling</H2>
</a>


<hr>
<A name=8.5.1>
<H3>8.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Double-Number word set</B> shall be appended
to the label of any Standard System that provides all of the
Double-Number word set.
<P>

The phrase <B>Providing name(s) from the Double-Number Extensions word
set</B> shall be appended to the label of any Standard System that
provides portions of the Double-Number Extensions word set.
<P>

The phrase <B>Providing the Double-Number Extensions word set</B> shall
be appended to the label of any Standard System that provides all of the
Double-Number and Double-Number Extensions word sets.

<P>


<hr>
<A name=8.5.2>
<H3>8.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Double-Number word set</B> shall be appended
to the label of Standard Programs that require the system to provide the
Double-Number word set.
<P>

The phrase <B>Requiring name(s) from the Double-Number Extensions word
set</B> shall be appended to the label of Standard Programs that require
the system to provide portions of the Double-Number Extensions word set.
<P>

The phrase <B>Requiring the Double-Number Extensions word set</B> shall
be appended to the label of Standard Programs that require the system to
provide all of the Double-Number and Double-Number Extensions word sets.

<P>


<hr>
<A name=8.6>
<H2>8.6 Glossary</H2>
</a>


<hr>
<A name=8.6.1>
<H3>8.6.1 Double-Number words</H3>
</a>



<hr>
<A name=8.6.1.0360>
<code>
8.6.1.0360 <b>2CONSTANT</b>
</code>
</a>
<BR>
<B>two-constant</B>  DOUBLE
<BR>
<pre>
	( x1 x2 <B>"&lt;spaces&gt;name"</B> -- )
</pre>
<P>

Skip leading space delimiters.  Parse name delimited by a space.  Create
a definition for name with the execution semantics defined below.
<P>

name is referred to
as a <B>two-constant</B>.
<P>
<pre>
        <i>name</i> Execution: ( -- x1 x2 )
</pre>
<P>

Place cell
pair x1 x2 on the stack.
<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<a href=dpansa8.htm#A.8.6.1.0360>A.8.6.1.0360 2CONSTANT</a>
</code>

<P>

<hr>
<A name=8.6.1.0390>
<code>
8.6.1.0390 <b>2LITERAL</b>
</code>
</a>
<BR>
  <B>two-literal</B>   DOUBLE
<BR>
<P>
<pre>
        Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
	Compilation: ( x1 x2 -- )
</pre>
<P>

Append the run-time semantics
below to the current definition.
<P>
<pre>
        Run-time: ( -- x1 x2 )
</pre>
<P>

Place cell pair
x1 x2 on the stack.

<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.0390>A.8.6.1.0390 2LITERAL</a>
</code>

<P>

<hr>
<A name=8.6.1.0440>
<code>
8.6.1.0440 <b>2VARIABLE</b>
</code>
</a>
<BR>
<B>two-variable</B>  DOUBLE
<BR>
<pre>
	( <B>"&lt;spaces&gt;name"</B> -- )
</pre>

<P>

Skip leading space delimiters.  Parse name delimited by a space.  Create
a definition for name with the execution semantics defined below.
Reserve two consecutive cells of data space.
<P>

name is referred to
as a <B>two-variable</B>.
<P>
<pre>
        <i>name</i> Execution: ( -- a-addr )
</pre>
<P>

a-addr is the address of the first (lowest address) cell of two
consecutive cells in data space reserved by 2VARIABLE when it defined
name.  A program is responsible for initializing the contents.
<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing,
<A href=dpans6.htm#6.1.2410>6.1.2410 VARIABLE</a> ,
<a href=dpansa8.htm#A.8.6.1.0440>A.8.6.1.0440 2VARIABLE</a>
</code>


<P>

<hr>
<A name=8.6.1.1040>
<code>
8.6.1.1040 <b>D+</b>
</code>
</a>
<BR>
<B>d-plus</B>        DOUBLE
<BR>
<pre>
	( d1|ud1 d2|ud2 -- d3|ud3 )
</pre>

<P>

Add d2|ud2 to d1|ud1,
giving the sum d3|ud3.

<P>

<hr>
<A name=8.6.1.1050>
<code>
8.6.1.1050 <b>D-</b>
</code>
</a>
<BR>
<B>d-minus</B>       DOUBLE
<BR>
<pre>
	( d1|ud1 d2|ud2 -- d3|ud3 )
</pre>

<P>

Subtract d2|ud2 from d1|ud1,
giving the difference d3|ud3.

<P>

<hr>
<A name=8.6.1.1060>
<code>
8.6.1.1060 <b>D.</b>
</code>
</a>
<BR>
<B>d-dot</B> DOUBLE
<BR>
<pre>
	( d -- )
</pre>

<P>

Display d in
free field format.

<P>

<hr>
<A name=8.6.1.1070>
<code>
8.6.1.1070 <b>D.R</b>
</code>
</a>
<BR>
<B>d-dot-r</B>       DOUBLE
<BR>
<pre>
	( d n -- )
</pre>

<P>

Display d right aligned in a field n characters wide.  If the number of
characters required to display d is greater than n, all digits are
displayed with no leading spaces in a field as wide as necessary.

<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.1070>A.8.6.1.1070 D.R</a>
</code>

<P>

<hr>
<A name=8.6.1.1075>
<code>
8.6.1.1075 <b>D0&lt;</b>
</code>
</a>
<BR>
<B>d-zero-less</B>   DOUBLE
<BR>
<pre>
	( d -- flag )
</pre>

<P>

flag is true if and
only if d is less than zero.

<P>

<hr>
<A name=8.6.1.1080>
<code>
8.6.1.1080 <b>D0=</b>
</code>
</a>
<BR>
<B>d-zero-equals</B> DOUBLE
<BR>
<pre>
	( xd -- flag )
</pre>

<P>

flag is true if and
only if xd is equal to zero.

<P>

<hr>
<A name=8.6.1.1090>
<code>
8.6.1.1090 <b>D2*</b>
</code>
</a>
<BR>
<B>d-two-star</B>    DOUBLE
<BR>
<pre>
	( xd1 -- xd2 )
</pre>

<P>

xd2 is the result of shifting xd1 one bit toward the most-significant bit,
filling the vacated least-significant bit with zero.


<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.1090>A.8.6.1.1090 D2*</a>
</code>

<P>

<hr>
<A name=8.6.1.1100>
<code>
8.6.1.1100 <b>D2/</b>
</code>
</a>
<BR>
<B>d-two-slash</B>   DOUBLE
<BR>
<pre>
	( xd1 -- xd2 )
</pre>

<P>

xd2 is the result of shifting xd1 one bit toward the least-significant bit,
leaving the most-significant bit unchanged.

<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.1100>A.8.6.1.1100 D2/</a>
</code>

<P>

<hr>
<A name=8.6.1.1110>
<code>
8.6.1.1110 <b>D&lt;</b>
</code>
</a>
<BR>
<B>d-less-than</B>   DOUBLE
<BR>
<pre>
	( d1 d2 -- flag )
</pre>

<P>

flag is true if and only
if d1 is less than d2.

<P>

<hr>
<A name=8.6.1.1120>
<code>
8.6.1.1120 <b>D=</b>
</code>
</a>
<BR>
<B>d-equals</B>      DOUBLE
<BR>
<pre>
	( xd1 xd2 -- flag )
</pre>

<P>

flag is true if and only if xd1
is bit-for-bit the same as xd2.

<P>

<hr>
<A name=8.6.1.1140>
<code>
8.6.1.1140 <b>D&gt;S</b>
</code>
</a>
<BR>
<B>d-to-s</B>        DOUBLE
<BR>
<pre>
	( d -- n )
</pre>

<P>

n is the equivalent of d.  An ambiguous condition exists if d lies
outside the range of a signed single-cell number.


<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.1140>A.8.6.1.1140 D&gt;S</a>
</code>

<P>

<hr>
<A name=8.6.1.1160>
<code>
8.6.1.1160 <b>DABS</b>
</code>
</a>
<BR>
<B>d-abs</B> DOUBLE
<BR>
<pre>
	( d -- ud )
</pre>

<P>

ud is the
absolute value of d.

<P>

<hr>
<A name=8.6.1.1210>
<code>
8.6.1.1210 <b>DMAX</b>
</code>
</a>
<BR>
<B>d-max</B> DOUBLE
<BR>
<pre>
	( d1 d2 -- d3 )
</pre>

<P>

d3 is the
greater of d1 and d2.

<P>

<hr>
<A name=8.6.1.1220>
<code>
8.6.1.1220 <b>DMIN</b>
</code>
</a>
<BR>
<B>d-min</B> DOUBLE
<BR>
<pre>
	( d1 d2 -- d3 )
</pre>

<P>

d3 is the
lesser of d1 and d2.

<P>

<hr>
<A name=8.6.1.1230>
<code>
8.6.1.1230 <b>DNEGATE</b>
</code>
</a>
<BR>
<B>d-negate</B>      DOUBLE
<BR>
<pre>
	( d1 -- d2 )
</pre>

<P>

d2 is
the negation of d1.

<P>

<hr>
<A name=8.6.1.1820>
<code>
8.6.1.1820 <b>M*/</b>
</code>
</a>
<BR>
<B>m-star-slash</B>  DOUBLE
<BR>
<pre>
	( d1 n1 +n2 -- d2 )
</pre>

<P>

Multiply d1 by n1 producing the triple-cell intermediate result t.
Divide t by +n2 giving the double-cell quotient d2.  An ambiguous
condition exists if +n2 is zero or negative, or the quotient lies
outside of the range of a double-precision signed integer.

<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.1820>A.8.6.1.1820 M*/</a>
</code>

<P>

<hr>
<A name=8.6.1.1830>
<code>
8.6.1.1830 <b>M+</b>
</code>
</a>
<BR>
<B>m-plus</B>        DOUBLE
<BR>
<pre>
	( d1|ud1 n -- d2|ud2 )
</pre>

<P>

Add n to d1|ud1,
giving the sum d2|ud2.

<p>
<code>
See:
<a href=dpansa8.htm#A.8.6.1.1830>A.8.6.1.1830 M+</a>
</code>

<P>

<hr>
<A name=8.6.2>
<H3>8.6.2 Double-Number extension words</H3>
</a>

<hr>
<A name=8.6.2.0420>
<code>
8.6.2.0420 <b>2ROT</b>
</code>
</a>
<BR>
<B>two-rote</B>      DOUBLE EXT
<pre>
	( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 )
</pre>

<P>

Rotate the top three cell pairs on the stack bringing cell pair x1 x2 to
the top of the stack.

<P>

<hr>
<A name=8.6.2.1270>
<code>
8.6.2.1270 <b>DU<</b>
</code>
</a>
<BR>
<B>d-u-less</B>      DOUBLE EXT
<BR>
<pre>
	( ud1 ud2 -- flag )
</pre>
<P>

flag is true if
and only if ud1 is less than ud2.



<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans9.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans9.htm/     851247120   500   0     100644  12982     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans8.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpans10.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=9.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>9. The optional Exception word set</H1>


<p>
<code>
See:
<a href=dpansa9.htm#A.9>A.9</a> The optional Exception word set
</code>
<p>


<hr>
<A name=9.1>
<H2>9.1 Introduction</H2>
</a>


<hr>
<A name=9.2>
<H2>9.2 Additional terms and notation</H2>
</a>

None.


<hr>
<A name=9.3>
<H2>9.3 Additional usage requirements</H2>
</a>

<p>
<code>
See:
<a href=dpansa9.htm#A.9.3>A.9.3</a> Additional usage requirements
</code>
<p>

<hr>
<A name=9.3.1>
<H3>9.3.1 THROW values</H3>
</a>

The 
<a href=dpans9.htm#9.6.1.2275>THROW</a> 
values {-255...-1} shall be used only as assigned by this
Standard.  The values {-4095...-256} shall be used only as assigned by a
system.
<P>

If the 
<a href=dpans11.htm>File-Access</a> or 
<a href=dpans14.htm>Memory-Allocation</a> word sets are implemented, it is
recommended that the non-zero values of ior lie within the range of
system THROW values, as defined above.  In an operating-system
environment, this can sometimes be accomplished by <B>biasing</B> the
range of operating-system exception-codes to fall within the THROW
range.
<P>

Programs shall not define values for use with THROW in the range
{-4095...-1}.

<P>

<hr>
<A name=9.3.2>
<H3>9.3.2 Exception frame</H3>
</a>

An exception frame is the implementation-dependent set of information
recording the current execution state necessary for the proper
functioning of 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> and 
<a href=dpans9.htm#9.6.1.2275>THROW</a>.  It often includes the depths of the
data stack and return stack.
<P>


<hr>
<A name=9.3.3>
<H3>9.3.3 Exception stack</H3>
</a>

A stack used for the nesting of exception frames by 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> and 
<a href=dpans9.htm#9.6.1.2275>THROW</a>.  It
may be, but need not be, implemented using the return stack.
<P>


<hr>
<A name=9.3.4>
<H3>9.3.4 Environmental queries</H3>
</a>

Append table 9.1
to table 3.5.
<P>

<code>
See:
<A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries
</code>
<P>

Table 9.1 - Environmental query strings
<P>


<PRE>
String          Value data type  Constant?   Meaning
------          ---------------  ---------   -------
EXCEPTION       flag             no          Exception word set present
EXCEPTION-EXT   flag             no          Exception extensions word set present

</PRE>

<P>

<hr>
<A name=9.3.5>
<H3>9.3.5 Possible actions on an ambiguous condition</H3>
</a>

A system choosing to execute 
<a href=dpans9.htm#9.6.1.2275>THROW</a> when detecting one of the ambiguous
conditions listed in table 9.3.6 shall use the throw code listed there.
<P>

<code>
See:
<A href=dpans3.htm#3.4.4>3.4.4</a> Possible actions on an ambiguous
condition
</code>

<P>

Table 9.2 - THROW code assignments
<P>


<PRE>
       Code     Reserved for
       ----     ------------
        -1      <a href=dpans6.htm#6.1.0670>ABORT</a>
        -2      <a href=dpans6.htm#6.1.0680>ABORT"</a>
        -3      stack overflow
        -4      stack underflow
        -5      return stack overflow
        -6      return stack underflow
        -7      do-loops nested too deeply during execution
        -8      dictionary overflow
        -9      invalid memory address
        -10     division by zero
        -11     result out of range
        -12     argument type mismatch
        -13     undefined word
        -14     interpreting a compile-only word
        -15     invalid <a href=dpans15.htm#15.6.2.1580>FORGET</a>
        -16     attempt to use zero-length string as a name
        -17     pictured numeric output string overflow
        -18     parsed string overflow
        -19     definition name too long
        -20     write to a read-only location
        -21     unsupported operation (e.g., <a href=dpans10.htm#10.6.1.0742>AT-XY</a> on a
                too-dumb terminal)
        -22     control structure mismatch
        -23     address alignment exception
        -24     invalid numeric argument
        -25     return stack imbalance
        -26     loop parameters unavailable
        -27     invalid recursion
        -28     user interrupt
        -29     compiler nesting
        -30     obsolescent feature
        -31     <a href=dpans6.htm#6.1.0550>>BODY</a> used on non-<a href=dpans6.htm#6.1.1000>CREATE</a>d definition
        -32     invalid name argument (e.g., <a href=dpans6.htm#6.2.2295>TO</a> xxx)
        -33     block read exception
        -34     block write exception
        -35     invalid block number
        -36     invalid file position
        -37     file I/O exception
        -38     non-existent file
        -39     unexpected end of file
        -40     invalid <a href=dpans6.htm#6.1.0750>BASE</a> for floating point conversion
        -41     loss of precision
        -42     floating-point divide by zero
        -43     floating-point result out of range
        -44     floating-point stack overflow
        -45     floating-point stack underflow
        -46     floating-point invalid argument
        -47     compilation word list deleted
        -48     invalid <a href=dpans6.htm#6.1.2033>POSTPONE</a>
        -49     search-order overflow
        -50     search-order underflow
        -51     compilation word list changed
        -52     control-flow stack overflow
        -53     exception stack overflow
        -54     floating-point underflow
        -55     floating-point unidentified fault
        -56     <a href=dpans6.htm#6.1.2050>QUIT</a>
        -57     exception in sending or receiving a character
        -58     <a href=dpans15.htm#15.6.2.2532>[IF]</a>, <a href=dpans15.htm#15.6.2.2531>[ELSE]</a>, or <a href=dpans15.htm#15.6.2.2533>[THEN]</a> exception
</PRE>

<P>

<hr>
<A name=9.3.6>
<H3>9.3.6 Exception handling</H3>
</a>

There are several methods of coupling 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> and 
<a href=dpans9.htm#9.6.1.2275>THROW</a> to other
procedural nestings.  The usual nestings are the execution of
definitions, use of the return stack, use of loops, instantiation of
locals and nesting of input sources (i.e., with 
<a href=dpans7.htm#7.6.1.1790>LOAD</a>, 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>, or
<a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a>).
<P>

When a THROW returns control to a CATCH, the system shall un-nest not
only definitions, but also, if present, locals and input source
specifications, to return the system to its proper state for continued
execution past the CATCH.
<P>
<code>
See:
<a href=dpansa9.htm#A.9.3.6>A.9.3.6</a> Exception handling
</code>
<p>


<hr>
<A name=9.4>
<H2>9.4 Additional documentation requirements</H2>
</a>



<hr>
<A name=9.4.1>
<H3>9.4.1 System documentation</H3>
</a>



<hr>
<A name=9.4.1.1>
<H3>9.4.1.1 Implementation-defined options</H3>
</a>

<UL>
<LI>Values used in the system by 
<a href=dpans9.htm#9.6.1.0875>9.6.1.0875</a> CATCH and 
<a href=dpans9.htm#9.6.1.2275>9.6.1.2275</a> THROW
(<a href=dpans9.htm#9.3.1>9.3.1</a> THROW values, 
<a href=dpans9.htm#9.3.5>9.3.5</a> 
Possible actions on an ambiguous condition).
</UL>
<P>


<hr>
<A name=9.4.1.2>
<H3>9.4.1.2 Ambiguous conditions</H3>
</a>

<UL>
<LI>no additional requirements.
</UL>
<P>


<hr>
<A name=9.4.1.3>
<H3>9.4.1.3 Other system documentation</H3>
</a>

<UL>
<LI>no additional requirements.
</UL>

<P>


<hr>
<A name=9.4.2>
<H3>9.4.2 Program documentation</H3>
</a>

<UL>
<LI>no additional requirements.
</UL>


<hr>
<A name=9.5>
<H2>9.5 Compliance and labeling</H2>
</a>



<hr>
<A name=9.5.1>
<H3>9.5.1 ANS Forth systems</H3>
</a>

The phrase <B>Providing the Exception word set</B> shall be appended to
the label of any Standard System that provides all of the Exception word
set.
<P>

The phrase <B>Providing name(s) from the Exception Extensions word
set</B> shall be appended to the label of any Standard System that
provides portions of the Exception Extensions word set.
<P>

The phrase <B>Providing the Exception Extensions word set</B> shall be
appended to the label of any Standard System that provides all of the
Exception and Exception Extensions word sets.
<P>



<hr>
<A name=9.5.2>
<H3>9.5.2 ANS Forth programs</H3>
</a>

The phrase <B>Requiring the Exception word set</B> shall be appended to
the label of Standard Programs that require the system to provide the
Exception word set.
<P>

The phrase <B>Requiring name(s) from the Exception Extensions word
set</B> shall be appended to the label of Standard Programs that require
the system to provide portions of the Exception Extensions word set.
<P>

The phrase <B>Requiring the Exception Extensions word set</B> shall be
appended to the label of Standard Programs that require the system to
provide all of the Exception and Exception Extensions word sets.

<P>


<hr>
<A name=9.6>
<H2>9.6 Glossary</H2>
</a>


<hr>
<A name=9.6.1>
<H3>9.6.1 Exception words</H3>
</a>



<hr>
<A name=9.6.1.0875>
<code>
9.6.1.0875 <b>CATCH</b>
</code>
</a>
<BR>
EXCEPTION
<BR>
<pre>
	( i*x xt -- j*x 0 | i*x n )
</pre>
<P>

Push an exception frame on the exception stack and then execute the
execution token xt (as with 
<a href=dpans6.htm#6.1.1370>EXECUTE</a>) 
in such a way that control can be
transferred to a point just after CATCH if 
<a href=dpans9.htm#9.6.1.2275>THROW</a> is executed during the
execution of xt.
<P>

If the execution of xt completes normally (i.e., the exception frame
pushed by this CATCH is not popped by an execution of THROW) pop the
exception frame and return zero on top of the data stack, above whatever
stack items would have been returned by xt EXECUTE.  Otherwise, the
remainder of the execution semantics are given by THROW.

<P>

<hr>
<A name=9.6.1.2275>
<code>
9.6.1.2275 <b>THROW</b>
</code>
</a>
<BR>
EXCEPTION
<BR>
<pre>
	( k*x n -- k*x | i*x n )
</pre>
<P>

If any bits of n are non-zero, pop the topmost exception frame from the
exception stack, along with everything on the return stack above that
frame.  Then restore the input source specification in use before the
corresponding 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> 
and adjust the depths of all stacks defined by this
Standard so that they are the same as the depths saved in the exception
frame (i is the same number as the i in the input arguments to the
corresponding CATCH), put n on top of the data stack, and transfer
control to a point just after the CATCH that pushed that exception
frame.
<P>

If the top of the stack is non zero and there is no exception frame on
the exception stack, the behavior is as follows:
<P>

If n is minus-one (-1), perform the function of 
<a href=dpans6.htm#6.1.0670>6.1.0670</a> ABORT (the
version of ABORT in the Core word set), displaying no message.
<P>

If n is minus-two, perform the function of 
<a href=dpans6.htm#6.1.0680>6.1.0680</a> ABORT" (the version
of ABORT" in the Core word set), displaying the characters ccc
associated with the ABORT" that generated the THROW.
<P>

Otherwise, the system may display an implementation-dependent message
giving information about the condition associated with the THROW code n.
Subsequently, the system shall perform the function of 
<a href=dpans6.htm#6.1.0670>6.1.0670</a> ABORT
(the version of ABORT in the Core word set).
<P>

<p>
<code>
See:
<a href=dpansa9.htm#A.9.6.1.2275>A.9.6.1.2275 THROW</a>
</code>
<p>

<hr>
<A name=9.6.2>
<H3>9.6.2 Exception extension words</H3>
</a>

<hr>
<A name=9.6.2.0670>
<code>
9.6.2.0670 <b>ABORT</b>
</code>
</a>
<br>
EXCEPTION EXT
<P>

Extend the semantics of 
<a href=dpans6.htm#6.1.0670>6.1.0670</a> ABORT to be:
<P>

<pre>
	( i*x -- ) ( R: j*x -- )
</pre>
<P>

Perform the function of -1 
<a href=dpans9.htm#9.6.1.2275>THROW</a> .
<P>


<hr>
<A name=9.6.2.0680>
<code>
9.6.2.0680 <b>ABORT"</b>
</code>
</a>
<br>
<B>abort-quote</B>   EXCEPTION EXT
<P>
Extend the semantics of 
<a href=dpans6.htm#6.1.0680>6.1.0680</a> ABORT" to be:
<P>
<pre>
        Interpretation: Interpretation semantics for this word are undefined.
</pre>
<P>
<pre>
        Compilation: ( <B>"ccc&lt;quote&gt;"</B> -- )
</pre>
<P>

Parse ccc delimited by a " (double-quote).  Append the run-time semantics
given below to the current definition.
<P>

<pre>
        Run-time:       ( i*x x1 --  | i*x ) ( R: j*x --  | j*x )
</pre>
<P>

Remove x1 from the stack.  If any bit of x1 is not zero, perform the function
of -2 
<a href=dpans9.htm#9.6.1.2275>THROW</a>, 
displaying ccc if there is no exception frame on the exception
stack.
<P>

<code>
See:
<A href=dpans3.htm#3.4.1>3.4.1</a> Parsing
</code>
<P>


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpans10.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpans94.txt/    823722300   500   0     100644  4515      `

+-----------------------------------------------+
| Greetings from the X3J14 Technical Committee. |
| This message has been prepared on 3 Feb 95    |
| by direction of TC Chair.  It was revised on  |
| 3 Jan 96 to correct copyright notice, misuse  |
| of the acronym ANS, and the section beginning |
| with NOTE:, as requested by X3 Secretariat.   |
+-----------------------------------------------+

The Technical Committee announces the posting of a file
known as  dpans94.zip  for retrieval on the Internet.

When expanded this .zip file yields the following three files:

	dpans94.doc   Microsoft Word for Windows 2.0 format,
                      produced by Word 6.0 for Windows.

	dpans94.txt   This file you are reading now

	notice.txt    a file which reads as follows:

[begin notice.txt]
==========================================================================
Copyright (c) 1994 by ITI, X3 Secretariat.  All rights reserved.

This is a working document of Technical Committee X3J14 which represents
the last draft of American National Standard Forth submitted to ANSI for
publication.  Permission is hereby granted to copy this document provided
that it is copied in its entirety without alteration or as altered by
(1) adding text that is clearly marked as an insertion; (2) shading or
highlighting existing text; and/or (3) deleting examples.

Specifically, permission is granted to use this working document as the
foundation for textbooks, system manuals, and online documentation so long
as the requirements in the preceding paragraph are met and the resulting
product addresses a technical need that is not practically met by the
official American National Standard.

NOTE:  The material described herein is taken from the working paper for
the Draft Proposed American National Standard, Programming Language Forth.
Approval and technical development work is being conducted by Accredited
Standards Committee X3 (Information Technology), and by its Technical
Committee X3J14 (Programming Language Forth), respectively.

This material *is not* intended as a substitute for the official American
National Standard Forth document published by ANSI.  In the event of
conflict, only the printed document (X3.215-1994) represents the official
American National Standard.

To obtain the official standard, please contact:
   the American National Standards Institute Sales Department,
   at (212) 642-4900 or FAX (212) 302-1286,
or Global Engineering Documents,
   at (800) 854-7179 or FAX (303) 843-9880,
and request Document X3.215-1994.  Thank you very much for your interest.
==========================================================================
[end notice.txt]

If you repost this material, please repost the entire original .zip file
as you retrieved it so that the original authentication signature is
preserved and there is some evidence of the integrity of the document.

The original versions of these files are available via anonymous FTP
(login=anonymous, password=email-address) from ftp.uu.net which is
accessible 24 hours per day by any host whose IP address has a valid
domain name that can be determined by the that server using inverse DNS.

The URL for the fille is:

        ftp://ftp.uu.net/vendor/minerva/x3j14/dpans94.zip
or      file://ftp.uu.net/vendor/minerva/x3j14/dpans94.zip

A WWW (html) page pointing to these files is accessible using the URL:

        HREF=file://ftp.uu.net/vendor/minerva/uathena.htm

This .zip file was produced by PKZIP 2.04g with authentication enabled
and, when decompressed, will display:

        Authentic files Verified!   # MYD772
        ATHENA Programming, Inc.
        [followed by the content of the notice.txt file]

Copies of PKUNZIP are readily available on most archive sites including,
undoubtedly, ftp.uu.net.

The TC would appreciate your letting us know how you have used this file.
Comments and suggestions may be sent to either of the following e-mail
addresses:

        x3j14@minerva.com - TC members only.
        ANSForth@minerva.com - TC members as well as many people
           who have subscribed to this mailgroup.  Anything sent
           to the ansforth list is automatically crossposted onto
           comp.lang.forth as well.

If you wish to direct mail to individual TC members, the above mailgroup
lists may be retrieved by fingering the user  ansi  at the host
med3.minerva.com

Best Wishes to all!


dpansa1.htm/    845512800   500   0     100644  7316      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpans17.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa2.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>A. Rationale (informative annex)</H1>


<hr>
<a name=A.1>
<H2>A.1 Introduction</H2>
</a>

<hr>
<a name=A.1.1></A>
<H3>A.1.1 Purpose</H3>
</a>


<hr>
<a name=A.1.2>
<H3>A.1.2 Scope</H3>
</a>

This Standard is more extensive than previous industry standards for the Forth
language.  Several things made this necessary:

<UL>
<LI>the desire to resolve conflicts between previous standards;
<LI>the need to eliminate semantic ambiguities and other inadequacies;
<LI>the requirement to standardize common practice, where possible
resolving divergences in a way that minimizes the cost of compliance;
<LI>the desire to standardize common system techniques, including those
germane to hardware.
</UL>
<P>

The result of the effort to satisfy all of these objectives is a
Standard arranged so that the required word set remains small.  Thus ANS
Forth can be provided for resource-constrained embedded systems.  Words
beyond those in the required word set are organized into a number of
optional word sets and their extensions, enabling implementation of
tailored systems that are Standard.

<P>

When judging relative merits, the members of the X3J14 Technical
Committee were guided by the following goals (listed in alphabetic
order):

<P>

<DL>
<DT><B>Consistency</B>   
<DD>The Standard provides a functionally complete
set of words
with minimal functional overlap.

<DT><B>Cost of compliance</B>     
<DD>This goal includes such issues as common
practice, how
much existing code would be broken by the proposed change, and the amount of
effort required to bring existing applications and systems into conformity
with the Standard.

<DT><B>Efficiency</B>     
<DD>Execution speed, memory compactness.

<DT><B>Portability</B>    
<DD>Words chosen for inclusion should be free of
system-dependent
features.

<DT><B>Readability</B>    
<DD>Forth definition names should clearly delineate
their
behavior.  That behavior should have an apparent simplicity which supports
rapid understanding.  Forth should be easily taught and support readily
maintained code.

<DT><B>Utility</B> 
<DD>Be judged to have sufficiently essential functionality
and frequency
of use to be deemed suitable for inclusion.</DL>


<P>

<hr>
<a name=A.1.3>
<H3>A.1.3 Document organization</H3>
</a>


<hr>
<a name=A.1.3.1>
<H4>A.1.3.1 Word sets</H4>
</a>

From the beginning, the X3J14 Technical Committee faced not only
conflicting ideas as to what <B>real</B> Forth is, but also conflicting
needs of the various groups within the Forth community.  At one extreme
were those who pressed for a <B>bare</B> Forth.  At the other extreme
were those who wanted a <B>fat</B> Forth.  Many were somewhere in
between.  All were convinced of the rightness of their own position and
of the wrongness of at least one of the two extremes.  The committee's
composition reflected this full range of interests.

<P>

The approach we have taken is to define a 
<a href=dpans6.htm#6.1>Core word set</a> 
establishing a
greatest lower bound for required system functionality and to provide a
portfolio of optional word sets for special purposes.  This simple
approach parallels the fundamental nature of Forth as an extensible
language, and thereby achieves a kind of meta-extensibility.

<P>

With this key, high-level compromise, regardless of the actual makeup of
the individual word sets, a firm and workable framework is established
for the long term.  One may or may not agree that there should be a
<a href=dpans13.htm>Locals word set</a>, 
or that the word 
<a href=dpans6.htm#6.2.0945>COMPILE,</a> 
belongs in the 
<a href=dpans6.htm#6.2>Core Extensions word set</a>.  
But at least there is a mechanism whereby such
things can be included in a logical and orderly manner.

<P>

Several implications of this scheme of optional word sets are
significant.

<P>

First, ANS Forth systems can continue to be implemented on a greater
range of hardware than could be claimed by almost any other single
language.  Since only the 
Core word set is required, very limited
hardware will be able to accommodate an ANS Forth implementation.

<P>

Second, a greater degree of portability of applications, and of
programmers, is anticipated.  The optional word sets standardize various
functions (e.g., floating point) that were widely implemented before,
but not with uniform definition names and methodologies, nor the same
levels of completeness.  With such words now standardized in the
optional word sets, communications between programmers - verbally, via
magazine or journal articles, etc.  - will leap to a new level of
facility, and the shareability of code and applications should rise
dramatically.

<P>

Third, ANS Forth systems may be designed to offer the user the power to
selectively, even dynamically, include or exclude one or more of the
optional word sets or portions thereof.  Also, lower-priced products may
be offered for the user who needs the Core word set and not much more.
Thus, virtually unlimited flexibility will be available to the user.

<P>

But these advantages have a price.  The burden is on the user to decide
what capabilities are desired, and to select product offerings
accordingly, especially when portability of applications is important.
We do not expect most implementors to attempt to provide all word sets,
but rather to select those most valuable to their intended markets.

<P>

The basic requirement is that if the implementor claims to have a
particular optional word set the entire required portion of that word
set must be available.  If the implementor wishes to offer only part of
an optional word set, it is acceptable to say, for example, <B>This
system offers portions of the [named] word set</B>, particularly if the
selected or excluded words are itemized clearly.

<P>

Each optional word set will probably appeal to a particular
constituency.  For example, scientists performing complex mathematical
analysis may place a higher value on the 
<a href=dpans12.htm>Floating-Point word set</a> 
than
programmers developing simple embedded controllers.  As in the case of
the core extensions, we expect implementors to offer those word sets
they expect will be valued by their users.

<P>

Optional word sets may be offered in source form or otherwise factored
so that the user may selectively load them.

<P>

The extensions to the optional word sets include words which are deemed
less essential to performing the primary activity supported by the word
set, though clearly relevant to it.  As in the case of the Core
Extensions, implementors may selectively add itemized subsets of a word
set extension providing the labeling doesn't mislead the user into
thinking incorrectly that all words are present.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa2.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa10.htm/   845512800   500   0     100644  11039     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa9.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa11.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.10>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.<a href=dpans10.htm>10</a> 
The optional Facility word set</H2>


<hr>
<a name=A.10.6>
<H3>A.<a href=dpans10.htm#10.6>10.6</a> 
Glossary</H3>
</a>

<hr>
<a name=A.10.6.1.0742>
A.<a href=dpans10.htm#10.6.1.0742>10.6.1.0742</a> 
AT-XY
</a>
<P>

Most implementors supply a method of positioning a cursor on a CRT
screen, but there is great variance in names and stack arguments.  This
version is supported by at least one major vendor.

<P>

<hr>
<a name=A.10.6.1.1755>
A.<a href=dpans10.htm#10.6.1.1755>10.6.1.1755</a> 
KEY?
</a>
<P>

The Technical Committee has gone around several times on the stack
effects.  Whatever is decided will violate somebody's practice and
penalize some machine.  This way doesn't interfere with type-ahead on
some systems, while requiring the implementation of a single-character
buffer on machines where polling the keyboard inevitably results in the
destruction of the character.

<P>

Use of 
<a href=dpans6.htm#6.1.1750>KEY</a> 
or KEY? indicates that the application does not wish to
bother with non-character events, so they are discarded, in anticipation
of eventually receiving a valid character.  Applications wishing to
handle non-character events must use 
<a href=dpans10.htm#10.6.2.1305>EKEY</a> and 
<a href=dpans10.htm#10.6.2.1307>EKEY?</a>.  It is possible to
mix uses of KEY? / KEY and EKEY? / EKEY within a single application, but
the application must use KEY? and KEY only when it wishes to discard
non-character events until a valid character is received.

<P>

<hr>
<a name=A.10.6.2.1305>
A.<a href=dpans10.htm#10.6.2.1305>10.6.2.1305</a> 
EKEY
</a>
<P>

EKEY provides a standard word to access a system-dependent set of
<B>raw</B> keyboard events, including events corresponding to members of
the standard character set, events corresponding to other members of the
implementation-defined character set, and keystrokes that do not
correspond to members of the character set.

<P>

EKEY assumes no particular numerical correspondence between particular
event code values and the values representing standard characters.  On
some systems, this may allow two separate keys that correspond to the
same standard character to be distinguished from one another.

<P>

In systems that combine both keyboard and mouse events into a single
<B>event stream</B>, the single number returned by EKEY may be
inadequate to represent the full range of input possibilities.  In such
systems, a single <B>event record</B> may include a time stamp, the x,y
coordinates of the mouse position, the keyboard state, and the state of
the mouse buttons.  In such systems, it might be appropriate for EKEY to
return the address of an <B>event record</B> from which the other
information could be extracted.

<P>

Also, consider a hypothetical Forth system running under MS-DOS on a
PC-compatible computer.  Assume that the implementation-defined
character set is the <B>normal</B> 8-bit PC character set.  In that
character set, the codes from 0 to 127 correspond to ASCII characters.
The codes from 128 to 255 represent characters from various non-English
languages, mathematical symbols, and some graphical symbols used for
line drawing.  In addition to those characters, the keyboard can
generate various other <B>scan codes</B>, representing such
non-character events as arrow keys and function keys.

<P>

There may be multiple keys, with different scan codes, corresponding to
the same standard character.  For example, the character representing
the number <B>1</B> often appears both in the row of number keys above
the alphabetic keys, and also in the separate numeric keypad.

<P>

When a program asks the MS-DOS operating system for a keyboard event, it
receives either a single non-zero byte, representing a character, or a
zero byte followed by a <B>scan code</B> byte, representing a
non-character keyboard event (e.g., a function key).

<P>

EKEY represents each keyboard event as a single number, rather than as a
sequence of numbers.  For the system described above, the following
would be a reasonable implementation of EKEY and related words:

<P>

The 
<a href=dpans3.htm#3.2.6>MAX-CHAR</a>
environmental query would return 255.

<P>

Assume the existence of a word DOS-KEY ( -- char ) which executes the
MS-DOS <B>Direct STDIN Input</B> system call (Interrupt 21h, Function
07h) and a word DOS-KEY? ( -- flag) which executes the MS-DOS <B>Check
STDIN Status</B> system call (Interrupt 21h, Function 0Bh).

<PRE>
: EKEY?  ( -- flag )  DOS-KEY?  0&lt;&gt;  ;

: EKEY  ( -- u )  DOS-KEY  ?DUP 0= IF  DOS-KEY 256 +  THEN ;

: EKEY>CHAR  ( u -- u false | char true )
    DUP 255 &gt; IF          ( u )
    DUP 259 = IF           \ 259 is Ctrl-@ (ASCII NUL)
        DROP 0 TRUE EXIT   \ so replace with character
      THEN FALSE EXIT      \ otherwise extended character
    THEN  TRUE             \ normal extended ASCII char.
;

VARIABLE PENDING-CHAR   -1 PENDING-CHAR !

: KEY?  ( -- flag )
    PENDING-CHAR @ 0&lt; IF
      BEGIN  EKEY? WHILE
        EKEY EKEY&gt;CHAR IF
          PENDING-CHAR !  TRUE EXIT
        THEN DROP
      REPEAT  FALSE EXIT
    THEN  TRUE
;

: KEY  ( -- char )
    PENDING-CHAR @ 0&lt; IF
      BEGIN  EKEY  EKEY>CHAR 0=
      WHILE
        DROP
      REPEAT  EXIT
    THEN  PENDING-CHAR @  -1 PENDING-CHAR !
;
</PRE>

<P>

This is a full-featured implementation, providing the application
program with an easy way to either handle non-character events (with
EKEY), or to ignore them and to only consider <B>real</B> characters
(with 
<a href=dpans6.htm#6.1.1750>KEY</a>).

<P>

Note that EKEY maps scan codes from 0 to 255 into numbers from 256 to
511.  EKEY maps the number 259, representing the keyboard combination
Ctrl-Shift-@, to the character whose numerical value is 0 (ASCII NUL).
Many ASCII keyboards generate ASCII NUL for Ctrl-Shift-@, so we use that
key combination for ASCII NUL (which is otherwise unavailable from
MS-DOS, because the zero byte signifies that another scan-code byte
follows).

<P>

One consequence of using the <B>Direct STDIN Input</B> system call
(function 7) instead of the <B>STDIN Input</B> system call (function 8)
is that the normal DOS <B>Ctrl-C interrupt</B> behavior is disabled when
the system is waiting for input (Ctrl-C would still cause an interrupt
while characters are being output).  On the other hand, if the <B>STDIN
Input</B> system call (function 8) were used to implement EKEY, Ctrl-C
interrupts would be enabled, but Ctrl-Shift-@ would also cause an
interrupt, because the operating system would treat the second byte of
the 0,3 sequence as a Ctrl-C, even though the 3 is really a scan code
and not a character.  One <B>best of both worlds</B> solution is to use
function 8 for the first byte received by EKEY, and function 7 for the
scan code byte.  For example:

<PRE>
: EKEY  ( -- u )
    DOS-KEY-FUNCTION-8  ?DUP  0=  IF
      DOS-KEY-FUNCTION-7 DUP 3  =  IF
        DROP 0  ELSE  256 +
      THEN
    THEN
;
</PRE>

<P>

Of course, if the Forth implementor chooses to pass Ctrl-C through to
the program, without using it for its usual interrupt function, then DOS
function 7 is appropriate in both cases (and some additional care must
be taken to prevent a typed-ahead Ctrl-C from interrupting the Forth
system during output operations).

<P>

A Forth system might also choose a simpler implementation of KEY,
without implementing EKEY, as follows:

<PRE>
: KEY   ( -- char )  DOS-KEY  ;

: KEY?  ( -- flag )  DOS-KEY? 0&lt;&gt;  ;
</PRE>

<P>

The disadvantages of the simpler version are:

<P>

a) An application program that uses KEY, expecting to receive only valid
characters, might receive a sequence of bytes (e.g., a zero byte
followed by a byte with the same numerical value as the letter <B>A</B>)
that appears to contain a valid character, even though the user pressed
a key (e.g., function key 4) that does not correspond to any valid
character.

<P>

b) An application program that wishes to handle non-character events
will have to execute KEY twice if it returns zero the first time.  This
might appear to be a reasonable and easy thing to do.  However, such
code is not portable to other systems that do not use a zero byte as an
<B>escape</B> code.  Using the EKEY approach, the algorithm for handling
keyboard events can be the same for all systems; the system dependencies
can be reduced to a table or set of constants listing the
system-dependent key codes used to access particular application
functions.  Without EKEY, the algorithm, not just the table, is likely
to be system dependent.

<P>

Another approach to EKEY on MS-DOS is to use the BIOS <B>Read Keyboard
Status</B> function (Interrupt 16h, Function 01h) or the related
<B>Check Keyboard</B> function (Interrupt 16h, Function 11h).  The
advantage of this function is that it allows the program to distinguish
between different keys that correspond to the same character (e.g.  the
two <B>1</B> keys).  The disadvantage is that the BIOS keyboard
functions read only the keyboard.  They cannot be <B>redirected</B> to
another <B>standard input</B> source, as can the DOS STDIN Input
functions.

<P>


<hr>
<a name=A.10.6.2.1306>
A.<a href=dpans10.htm#10.6.2.1306>10.6.2.1306</a>   
EKEY&gt;CHAR
</a>
<P>

EKEY&gt;CHAR translates a keyboard event into the corresponding member of
the character set, if such a correspondence exists for that event.

<P>

It is possible that several different keyboard events may correspond to
the same character, and other keyboard events may correspond to no
character.

<P>

<hr>
<a name=A.10.6.2.1325>
A.<a href=dpans10.htm#10.6.2.1325>10.6.2.1325</a> 
EMIT?
</a>
<P>

An indefinite delay is a device related condition, such as printer
off-line, that requires operator intervention before the device will
accept new data.

<P>

<hr>
<a name=A.10.6.2.1905>
A.<a href=dpans10.htm#10.6.2.1905>10.6.2.1905</a> 
MS
</a>
<P>

Although their frequencies vary, every system has a clock.  Since many
programs need to time intervals, this word is offered.  Use of
milliseconds as an internal unit of time is a practical <B>least common
denominator</B> external unit.  It is assumed implementors will use
<B>clock ticks</B> (whatever size they are) as an internal unit and
convert as appropriate.

<P>

<hr>
<a name=A.10.6.2.2292>
A.<a href=dpans10.htm#10.6.2.2292>10.6.2.2292</a> 
TIME&DATE
</a>
<P>

Most systems have a real-time clock/calendar.  This word gives portable
access to it.

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa11.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa11.htm/   845512740   500   0     100644  7987      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa10.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa12.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.11>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H3>A.11 The optional File-Access word set</H3>

Many Forth systems support access to a host file system, and many of
these support interpretation of Forth from source text files.  The
Forth-83 Standard did not address host OS files.  Nevertheless, a degree
of similarity exists among modern implementations.

<P>

For example, files must be opened and closed, created and deleted.
Forth file-system implementations differ mostly in the treatment and
disposition of the exception codes, and in the format of the
file-identification strings.  The underlying mechanism for creating
file-control blocks might or might not be visible.  We have chosen to
keep it invisible.

<P>

Files must also be read and written.  Text files, if supported, must be
read and written one line at a time.  Interpretation of text files
implies that they are somehow integrated into the text interpreter input
mechanism.  These and other requirements have shaped the file-access
extensions word set.

<P>

Most of the existing implementations studied use simple English words
for common host file functions: OPEN, CLOSE, READ, etc.  Although we
would have preferred to do likewise, there were so many minor variations
in implementation of these words that adopting any particular meaning
would have broken much existing code.  We have used names with a suffix
-FILE for most of these words.  We encourage implementors to conform
their single-word primitives to the ANS behaviors, and hope that if this
is done on a widespread basis we can adopt better definition names in a
future standard.

<P>

Specific rationales
for members of this word set follow.

<P>

<hr>
<a name=A.11.3>
<H3>A.11.3 Additional usage requirements</H3>
</a>

<hr>
<a name=A.11.3.2>
<H4>A.11.3.2 Blocks in files</H4>
</a>

Many systems reuse file identifiers; when a file is closed, a
subsequently opened file may be given the same identifier.  If the
original file has blocks still in block buffers, these will be
incorrectly associated with the newly opened file with disastrous
results.  The block buffer system must be flushed to avoid this.

<P>

<hr>
<a name=A.11.6>
<H3>A.11.6 Glossary</H3>
</a>


<hr>
<a name=A.11.6.1.0765>
A.11.6.1.0765 BIN
</a>
<P>

Some operating systems require that files be opened in a different mode
to access their contents as an unstructured stream of binary data rather
than as a sequence of lines.

<P>

The arguments to 
<a href=dpans11.htm#11.6.1.2080>READ-FILE</a> and 
<a href=dpans11.htm#11.6.1.2480>WRITE-FILE</a> are 
arrays of character
storage elements, each element consisting of at least 8 bits.  The
Technical Committee intends that, in BIN mode, the contents of these
storage elements can be written to a file and later read back without
alteration.  The Technical Committee has declined to address issues
regarding the impact of <B>wide</B> characters on the File and Block
word sets.

<P>

<hr>
<a name=A.11.6.1.1010>
A.11.6.1.1010 CREATE-FILE
</a>
<P>

Typical use:

<PRE>
: X .. S" TEST.FTH" R/W CREATE-FILE  ABORT" CREATE-FILE FAILED" ... ;
</PRE>
<P>

<hr>
<a name=A.11.6.1.1717>
A.11.6.1.1717 INCLUDE-FILE
</a>
<P>

Here are two implementation alternatives for saving the input source
specification in the presence of text file input:

<P>

1)      Save the file position (as returned by 
<a href=dpans11.htm#11.6.1.1520>FILE-POSITION</a>) of the beginning
of the line being interpreted.  To restore the input source specification,
seek to that position and re-read the line into the input buffer.

<P>

2)      Allocate a separate line buffer for each active text input file, using
that buffer as the input buffer.  This method avoids the <B>seek and reread</B>
step, and allows the use of <B>pseudo-files</B> such as pipes and other
sequential-access-only communication channels.

<P>

<hr>
<a name=A.11.6.1.1718>
A.11.6.1.1718 INCLUDED
</a>
<P>

Typical use:     <code>... S" filename" INCLUDED ...</code>

<P>

<hr>
<a name=A.11.6.1.1970>
A.11.6.1.1970 OPEN-FILE
</a>
<P>

Typical use:

<PRE>
: X .. S" TEST.FTH" R/W OPEN-FILE  ABORT" OPEN-FILE FAILED" ... ;
</PRE>
<P>

<hr>
<a name=A.11.6.1.2080>
A.11.6.1.2080 READ-FILE
</a>
<P>

A typical sequential
file-processing algorithm might look like:

<PRE>
   BEGIN                (  )
   ... READ-FILE THROW  ( length )
   ?DUP WHILE           ( length )
   ...                  (  )
   REPEAT               (  )
</PRE>

<P>

In this example, 
<a href=dpans9.htm#9.6.1.2275>THROW</a> 
is used to handle (unexpected) exception
conditions, which are reported as non-zero values of the ior return
value from READ-FILE.  End-of-file is reported as a zero value of the
<B>length</B> return value.

<P>

<hr>
<a name=A.11.6.1.2090>
A.11.6.1.2090 READ-LINE
</a>
<P>

Implementations are allowed to store the line terminator in the memory
buffer in order to allow the use of line reading functions provided by
host operating systems, some of which store the terminator.  Without
this provision, a temporary buffer might be needed.  The two-character
limitation is sufficient for the vast majority of existing operating
systems.  Implementations on host operating systems whose line
terminator sequence is longer than two characters may have to take
special action to prevent the storage of more than two terminator
characters.

<P>

Standard Programs may not depend on the presence of any such terminator
sequence in the buffer.

<P>

A typical line-oriented sequential file-processing algorithm might look
like:

<PRE>
   BEGIN                (  )
   ... READ-LINE THROW  ( length not-eof-flag )
   WHILE                ( length )
   ...                  (  )
   REPEAT DROP          (  )
</PRE>

<P>

In this example, 
<a href=dpans9.htm#9.6.1.2275>THROW</a> 
is used to handle (unexpected) I/O exception condition,
which are reported as non-zero values of the <B>ior</B> return value from
READ-LINE.

<P>

READ-LINE needs a separate end-of-file flag because empty (zero-length) lines
are a routine occurrence, so a zero-length line cannot be used to signify
end-of-file.

<P>

<hr>
<a name=A.11.6.1.2165>
A.11.6.1.2165 S"
</a>
<P>

Typical use:    <code>... S" ccc" ...</code>

<P>

The interpretation semantics for S" are intended to provide a simple
mechanism for entering a string in the interpretation state.  Since an
implementation may choose to provide only one buffer for interpreted
strings, an interpreted string is subject to being overwritten by the
next execution of S" in interpretation state.  It is intended that no
standard words other than S" should in themselves cause the interpreted
string to be overwritten.  However, since words such as 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>, 
<a href=dpans7.htm#7.6.1.1790>LOAD</a>,
<a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a> and 
<a href=dpans11.htm#11.6.1.1718>INCLUDED</a> 
can result in the interpretation of arbitrary
text, possibly including instances of S", the interpreted string may be
invalidated by some uses of these words.

<P>

When the possibility of overwriting a string can arise, it is prudent to
copy the string to a <B>safe</B> buffer allocated by the application.

<P>

Programs wishing to parse in the fashion of S" are advised to use 
<a href=dpans6.htm#6.2.2008>PARSE</a>
or 
<a href=dpans6.htm#6.1.2450>WORD</a> 
<a href=dpans6.htm#6.1.0980>COUNT</a> 
instead of S", preventing the overwriting of the
interpreted string buffer.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa12.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa12.htm/   851248200   500   0     100644  11380     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa11.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa13.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.12>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>
 
<H2>A.12 The optional Floating-Point word set</H2>

The Technical Committee has considered many proposals dealing with the
inclusion and makeup of the Floating-Point Word Sets in ANS Forth.
Although it has been argued that ANS Forth should not address
floating-point arithmetic and numerous Forth applications do not need
floating-point, there are a growing number of important Forth
applications from spreadsheets to scientific computations that require
the use of floating-point arithmetic.  Initially the Technical Committee
adopted proposals that made the Forth Vendors Group Floating-Point
Standard, first published in 1984, the framework for inclusion of
Floating-Point in ANS Forth.  There is substantial common practice and
experience with the Forth Vendors Group Floating-Point Standard.
Subsequently the Technical Committee adopted proposals that placed the
basic floating-point arithmetic, stack and support words in the
Floating-Point word set and the floating-point transcendental functions
in the Floating-Point Extensions word set.  The Technical Committee also
adopted proposals that:

<UL>
<LI>changed names for clarity and consistency; e.g., REALS to 
<a href=dpans12.htm#12.6.1.1556>FLOATS</a>, and
REAL+ to 
<a href=dpans12.htm#12.6.1.1555>FLOAT+</a> .
<LI>removed words; e.g., FPICK .
<LI>added words for completeness and increased functionality; e.g.,
<a href=dpans12.htm#12.6.2.1616>FSINCOS</a>, 
<a href=dpans12.htm#12.6.2.1640>F~</a>, 
<a href=dpans12.htm#12.6.2.1204>DF@</a>, 
<a href=dpans12.htm#12.6.2.1203>DF!</a>, 
<a href=dpans12.htm#12.6.2.2203>SF@</a> and 
<a href=dpans12.htm#12.6.2.2202>SF!</a>
</UL>
<P>

Several issues concerning the Floating-Point word set were resolved by
consensus in the Technical Committee:

<P>

Floating-point stack: By default the floating-point stack is separate
from the data and return stacks; however, an implementation may keep
floating-point numbers on the data stack.  A program can determine
whether floating-point numbers are kept on the data stack by passing the
string 
<a href=dpans12.htm#12.3.4>FLOATING-STACK</a> to 
<a href=dpans6.htm#6.1.1345>ENVIRONMENT?</a> 
It is the experience of several
members of the Technical Committee that with proper coding practices it
is possible to write floating-point code that will run identically on
systems with a separate floating-point stack and with floating-point
numbers kept on the data stack.

<P>

Floating-point input: The current base must be 
<a href=dpans6.htm#6.1.1170>DECIMAL</a>.  Floating-point
input is not allowed in an arbitrary base.  All floating-point numbers
to be interpreted by an ANS Forth system must contain the exponent
indicator <B>E</B> (see
<a href=dpans12.htm#12.3.7>12.3.7</a> Text interpreter input number
conversion).
Consensus in the Technical Committee deemed this form of
floating-point input to be in more common use than the alternative that
would have a floating-point input mode that would allow numbers with
embedded decimal points to be treated as floating-point numbers.

<P>

Floating-point representation: Although the format and precision of the
significand and the format and range of the exponent of a floating-point
number are implementation defined in ANS Forth, the Floating-Point
Extensions word set contains the words DF@, SF@, DF!, and SF! for
fetching and storing double- and single-precision IEEE
floating-point-format numbers to memory.  The IEEE floating-point format
is commonly used by numeric math co-processors and for exchange of
floating-point data between programs and systems.

<P>


<hr>
<a name=A.12.3>
<H3>A.12.3 Additional usage requirements</H3>
</a>



<hr>
<a name=A.12.3.5>
<H4>A.12.3.5 Address alignment</H4>
</a>

In defining custom floating-point data structures, be aware that 
<a href=dpans6.htm#6.1.1000>CREATE</a>
doesn't necessarily leave the data space pointer aligned for various
floating-point data types.  Programs may comply with the requirement for
the various kinds of floating-point alignment by specifying the
appropriate alignment both at compile-time and execution time.  For
example:

<PRE>
: FCONSTANT ( F:  r -- )
    CREATE FALIGN  HERE  1 FLOATS ALLOT  F!
    DOES> ( F:  -- r )  FALIGNED F@ ;
</PRE>

<P>


<hr>
<a name=A.12.3.7>
<H4>A.12.3.7 Text interpreter input number conversion</H4>
</a>

The Technical Committee has more than once received the suggestion that
the text interpreter in Standard Forth systems should treat numbers that
have an embedded decimal point, but no exponent, as floating-point
numbers rather than double cell numbers.  This suggestion, although it
has merit, has always been voted down because it would break too much
existing code; many existing implementations put the full digit string
on the stack as a double number and use other means to inform the
application of the location of the decimal point.

<p>
<code>
See:
<a href=a0004.htm>RFI 0004</a> Number Conversion
</code>
<P>

<hr>
<a name=A.12.6>
<H3>A.12.6 Glossary</H3>
</a>



<hr>
<a name=A.12.6.1.0558>A.12.6.1.0558 &gt;FLOAT</A>
<P>

&gt;FLOAT enables programs to read floating-point data in legible ASCII
format.  It accepts a much broader syntax than does the text interpreter
since the latter defines rules for composing source programs whereas
&gt;FLOAT defines rules for accepting data.  &gt;FLOAT is defined as broadly
as is feasible to permit input of data from ANS Forth systems as well as
other widely used standard programming environments.

<P>

This is a synthesis of common FORTRAN practice.  Embedded spaces are
explicitly forbidden in much scientific usage, as are other field
separators such as comma or slash.

<P>

While &gt;FLOAT is not required to treat a string of blanks as zero, this
behavior is strongly encouraged, since a future version of ANS Forth may
include such a requirement.

<P>

<hr>
<a name=A.12.6.1.1427>A.12.6.1.1427 F.</A>
<P>

For example, 1E3 F. displays 1000. .

<P>

<hr>
<a name=A.12.6.1.1492>A.12.6.1.1492 FCONSTANT</A>
<P>

Typical use:    <code>r FCONSTANT name</code>

<P>

<hr>
<a name=A.12.6.1.1552>A.12.6.1.1552 FLITERAL</A>
<P>

Typical use:    <code>: X ... [ ... ( r ) ] FLITERAL ... ;</code>

<P>

<hr>
<a name=A.12.6.1.1630>A.12.6.1.1630 FVARIABLE</A>
<P>

Typical use:    <code>FVARIABLE name</code>

<P>

<hr>
<a name=A.12.6.1.2143>A.12.6.1.2143 REPRESENT</A>
<P>

This word provides a primitive for floating-point display.  Some
floating-point formats, including those specified by IEEE-754, allow
representations of numbers outside of an implementation-defined range.
These include plus and minus infinities, denormalized numbers, and
others.  In these cases we expect that REPRESENT will usually be
implemented to return appropriate character strings, such as
<B>+infinity</B> or <B>nan</B>, possibly truncated.

<P>

<hr>
<a name=A.12.6.2.1489>A.12.6.2.1489 FATAN2</A>
<P>

<a href=dpans12.htm#12.6.2.1616>FSINCOS</a> 
and 
<a href=dpans12.htm#12.6.2.1489>FATAN2</a> 
are a complementary pair of operators which convert
angles to 2-vectors and vice-versa.  They are essential to most
geometric and physical applications since they correctly and
unambiguously handle this conversion in all cases except null vectors,
even when the tangent of the angle would be infinite.

<P>

FSINCOS returns a Cartesian unit vector in the direction of the given
angle, measured counter-clockwise from the positive X-axis.  The order
of results on the stack, namely y underneath x, permits the 2-vector
data type to be additionally viewed and used as a ratio approximating
the tangent of the angle.  Thus the phrase FSINCOS 
<a href=dpans12.htm#12.6.1.1430>F/</a> is functionally
equivalent to 
<a href=dpans12.htm#12.6.2.1625>FTAN</a>, 
but is useful over only a limited and discontinuous
range of angles, whereas FSINCOS and FATAN2 are useful for all angles.
This ordering has been found convenient for nearly two decades, and has
the added benefit of being easy to remember.  A corollary to this
observation is that vectors in general should appear on the stack in
this order.

<P>

The argument order for FATAN2 is the same, converting a vector in the
conventional representation to a scalar angle.  Thus, for all angles,
FSINCOS FATAN2 is an identity within the accuracy of the arithmetic and
the argument range of FSINCOS.  Note that while FSINCOS always returns a
valid unit vector, FATAN2 will accept any non-null vector.  An ambiguous
condition exists if the vector argument to FATAN2 has zero magnitude.

<P>

<hr>
<a name=A.12.6.2.1516>A.12.6.2.1516 FEXPM1</A>
<P>

This function allows accurate computation when its arguments are close
to zero, and provides a useful base for the standard exponential
functions.  Hyperbolic functions such as cosh(x) can be efficiently and
accurately implemented by using FEXPM1; accuracy is lost in this
function for small values of x if the word 
<a href=dpans12.htm#12.6.2.1515>FEXP</a> is used.

<P>

An important application of this word is in finance; say a loan is
repaid at 15% per year; what is the daily rate? On a computer with
single precision (six decimal digit) accuracy:

<P>

1.  Using
<a href=dpans12.htm#12.6.2.1553>FLN</a> and FEXP:
<P>

FLN of 1.15 = 0.139762,
divide by 365 = 3.82910E-4,
form the exponent using
FEXP = 1.00038, and
subtract one (1) and convert to percentage = 0.038%.

<P>

Thus we only have two digit accuracy.
<P>


2.  Using 
<a href=dpans12.htm#12.6.2.1554>FLNP1</a> and FEXPM1:

<P>

FLNP1 of 0.15 = 0.139762, (this is the same value as in the first example,
although with the argument closer to zero it may not be so)
divide by 365 = 3.82910E-4,
form the exponent and subtract one (1) using FEXPM1 = 3.82983E-4,
and convert to percentage = 0.0382983%.

<P>

This is full six digit accuracy.
<P>


The presence of this word allows the hyperbolic functions to be computed with
usable accuracy.  For example, the hyperbolic sine can be defined as:

<PRE>
: FSINH  ( r1 -- r2 )
    FEXPM1  FDUP  FDUP 1.0E0 F+  F/  F+  2.0E0 F/ ;
</PRE>

<P>

<hr>
<a name=A.12.6.2.1554>A.12.6.2.1554</a> FLNP1
<P>

This function allows accurate compilation when its arguments are close
to zero, and provides a useful base for the standard logarithmic
functions.  For example, 
<a href=dpans12.htm#12.6.2.1553>FLN</a> can be implemented as:


<PRE>
	: FLN   1.0E0 F-  FLNP1 ;
</PRE>
<P>
<code>
See: 
<a href=dpansa12.htm#A.12.6.2.1516>A.12.6.2.1516 FEXPM1</a>
</code>
<P>

<hr>
<a name=A.12.6.2.1616>A.12.6.2.1616</a> FSINCOS
<P>
<code>
See:  
<a href=dpansa12.htm#A.12.6.2.1489>A.12.6.2.1489 FATAN2</a>
</code>
<P>

<hr>
<a name=A.12.6.2.1640>A.12.6.2.1640</a> F~
<P>

This provides the three types of <B>floating point equality</B> in
common use -- <B>close</B> in absolute terms, exact equality as
represented, and <B>relatively close</B>.

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa13.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa13.htm/   850759500   500   0     100644  10822     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa12.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa14.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.13>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.13 The optional Locals word set</H2>

The Technical Committee has had a problem with locals.  It has been
argued forcefully that ANS Forth should say nothing about locals since:

<UL>
<LI>there is no clear accepted practice in this area;
<LI>not all Forth programmers use them or even know what they are; and
<LI>few implementations use the same syntax, let alone the same broad
usage rules and general approaches.
</UL>
<P>

It has also been argued, it would seem equally forcefully, that the lack
of any standard approach to locals is precisely the reason for this lack
of accepted practice since locals are at best non-trivial to implement
in a portable and useful way.  It has been further argued that users who
have elected to become dependent on locals tend to be locked into a
single vendor and have little motivation to join the group that it is
hoped will <B>broadly accept</B> ANS Forth unless the Standard addresses
their problems.

<P>

Since the Technical Committee has been unable to reach a strong
consensus on either leaving locals out or on adopting any particular
vendor's syntax, it has sought some way to deal with an issue that it
has been unable to simply dismiss.  Realizing that no single mechanism
or syntax can simultaneously meet the desires expressed in all the
locals proposals that have been received, it has simplified the problem
statement to be to define a locals mechanism that:

<UL>
<LI>is independent of any particular syntax;
<LI>is user extensible;
<LI>enables use of arbitrary identifiers, local in scope to a single
definition;
<LI>supports the fundamental cell size data types of Forth; and
<LI>works consistently, especially with respect to re-entrancy and
recursion.
</UL>
<P>

This appears to the Technical Committee to be what most of those who
actively use locals are trying to achieve with them, and it is at
present the consensus of the Technical Committee that if ANS Forth has
anything to say on the subject this is an acceptable thing for it to
say.

<P>

This approach, defining 
<a href=dpans13.htm#13.6.1.0086>(LOCAL)</a>, 
is proposed as one that can be used
with a small amount of user coding to implement some, but not all, of
the locals schemes in use.  The following coding examples illustrate how
it can be used to implement two syntaxes.

<p>

The syntax defined by this Standard and used in the systems of
Creative Solutions, Inc.:

<P>


<PRE>
   : LOCALS|  ( "name...name |" -- )
       BEGIN
         BL WORD   COUNT OVER C@
         [CHAR] | - OVER 1 - OR
       WHILE
         (LOCAL)
       REPEAT 2DROP   0 0 (LOCAL)
   ;
   IMMEDIATE

   : EXAMPLE  ( n -- n n**2 n**3 )
       LOCALS| N |   N  DUP N *  DUP N * ;
</PRE>

A proposed syntax: ( LOCAL name ) with additional usage rules:

<P>


<PRE>
   : LOCAL  ( "name" -- )  BL WORD COUNT (LOCAL) ;  IMMEDIATE

   : END-LOCALS  ( -- )  0 0 (LOCAL) ;  IMMEDIATE

   : EXAMPLE  ( n -- n n**2 n**3 )
       LOCAL N  END-LOCALS   N  DUP N *  DUP N * ;
</PRE>

<P>

Other syntaxes can be implemented, although some will admittedly require
considerably greater effort or in some cases program conversion.  Yet
other approaches to locals are completely incompatible due to gross
differences in usage rules and in some cases even scope identifiers.
For example, the complete local scheme in use at Johns Hopkins had
elaborate semantics that cannot be duplicated in terms of this model.

<P>

To reinforce the intent of section 
<a href=dpans13.htm>13</a>, here are two examples of actual use of
locals.  The first illustrates correct usage:

<P>

a)

<PRE>
: {  ( "name ... }" - )
    BEGIN  BL WORD COUNT
      OVER C@ [CHAR] }
      - OVER 1 -  OR 
    WHILE
      (LOCAL)
    REPEAT 2DROP 0 0 (LOCAL)
;  IMMEDIATE
</PRE>

<P>

b)

<PRE>
: JOE  ( a b c -- n )
    >R 2* R> 2DUP + 0
    { ANS 2B+C C 2B A }
    2 0 DO  1 ANS + I + TO ANS  ANS . CR  LOOP
    ANS . 2B+C . C . 2B . A . CR
    ANS
;
</PRE>
c) 
<PRE>
100 300 10 JOE .
</PRE>

<P>

The word { at a) defines a local declaration syntax that surrounds the
list of locals with braces.  It doesn't do anything fancy, such as
reordering locals or providing initial values for some of them, so
locals are initialized from the stack in the default order.  The
definition of JOE at b) illustrates a use of this syntax.  Note that
work is performed at execution time in that definition before locals are
declared.  It's OK to use the return stack as long as whatever is placed
there is removed before the declarations begin.

<P>

Note that before declaring locals, B is doubled, a subexpression (2B+C)
is computed, and an initial value (zero) for ANS is provided.  After
locals have been declared, JOE proceeds to use them.  Note that locals
may be accessed and updated within do-loops.  The effect of interpreting
line c) is to display the following values:

<P>

1 (ANS the first time through the loop), 
<BR>
3 (ANS the second time), 
<BR>
3 (ANS), 610 (2B+C), 10 (C), 600 (2B), 100 (A), 
<BR>
and 3 (ANS left on the stack by JOE). 
<BR>

<P>

The names of the locals vanish after JOE has been compiled.  The storage and
meaning of locals appear when JOE's locals are declared and vanish as JOE
returns to its caller at ; (semicolon).

<P>

A second set of examples illustrates various things that break the rules.  We
assume that the definitions of LOCAL and END-LOCALS above are present, along
with { from the preceding example.
<P>

d)      
<PRE>
: ZERO   0 POSTPONE LITERAL POSTPONE LOCAL ; IMMEDIATE
</PRE>
<P>

e)
<PRE>
: MOE  ( a b )
     ZERO TEMP  LOCAL B  1+ LOCAL A+  ZERO ANSWER ;
</PRE>

<P>

f)      
<PRE>
: BOB  ( a b c d )  { D C }  { B A } ;
</PRE>
<P>

Here are two definitions with various violations of rule 
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>a.  In
e) the declaration of TEMP is legal and creates a local whose initial
value is zero.  It's OK because the executable code that ZERO generates
precedes the first use of (LOCAL) in the definition.  However, the 1+
preceding the declaration of A+ is illegal.  Likewise the use of ZERO to
define ANSWER is illegal because it generates executable code between
uses of (LOCAL).  Finally, MOE terminates illegally (no END-LOCALS).
BOB in f) violates the rule against declaring two sets of locals.
<P>

g)      
<PRE>
: ANN  ( a b  -- b )  DUP >R  DUP IF { B A } THEN  R> ;
</PRE>
<P>

h)      
<PRE>
: JANE  ( a b -- n )  { B A }  A B + >R  A B -  R> / ;
</PRE>
<P>

ANN in g) violates two rules.  The IF ... THEN around the declaration
of its locals violates 
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>b, 
and the copy of B left on the return
stack before declaring locals violates 
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>c.  JANE in h) violates
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>d 
by accessing locals after placing the sum of A and B on the
return stack without first removing that sum.

<P>

i)      
<PRE>
: CHRIS  ( a b)
     { B A }  ['] A EXECUTE  5 ['] B >BODY !
     [ ' A ] LITERAL LEE ;
</PRE>

<P>

CHRIS in i) illustrates three violations of 
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>e.  The attempt to
<a href=dpans6.htm#6.1.1370>EXECUTE</a> 
the local called A is inconsistent with some implementations.
The store into B via 
<a href=dpans6.htm#6.1.0550>>BODY</a> 
is likely to cause tragic results with many
implementations; moreover, if locals are in registers they can't be
addressed as memory no matter what is written.

<P>

The third violation, in which an execution token for a definition's
local is passed as an argument to the word LEE, would, if allowed, have
the unpleasant implication that LEE could EXECUTE the token and obtain a
value for A from the particular execution of CHRIS that called LEE this
time.

<P>

<hr>
<a name=A.13.3>
<H3>A.13.3 Additional usage requirements</H3>
</a>

Rule 
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>d 
could be relaxed without affecting the integrity of the
rest of this structure.  
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>c could not be.

<P>

<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>b 
forbids the use of the data stack for local storage because no
usage rules have been articulated for programmer users in such a case.
Of course, if the data stack is somehow employed in such a way that
there are no usage rules, then the locals are invisible to the
programmer, are logically not on the stack, and the implementation
conforms.

<P>

The minimum required number of locals can (and should) be adjusted to
minimize the cost of compliance for existing users of locals.

<P>

Access to previously declared local variables is prohibited by Section
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>d 
until any data placed onto the return stack by the application
has been removed, due to the possible use of the return stack for
storage of locals.

<P>

Authorization for a Standard Program to manipulate the return stack
(e.g., via 
<a href=dpans6.htm#6.1.0580>&gt;R</a> 
<a href=dpans6.htm#6.1.2060>R&gt;</a>) 
while local variables are active overly constrains
implementation possibilities.  The consensus of users of locals was that
Local facilities represent an effective functional replacement for
return stack manipulation, and restriction of standard usage to only one
method was reasonable.

<P>

Access to Locals within 
<a href=dpans6.htm#6.1.1240>DO</a>..<a href=dpans6.htm#6.1.1800>LOOP</a>s 
is expressly permitted as an
additional requirement of conforming systems by Section 
<a href=dpans13.htm#13.3.3.2>13.3.3.2</a>g.
Although words, such as 
<a href=dpans13.htm#13.6.1.0086>(LOCALS)</a>, 
written by a System Implementor, may
require inside knowledge of the internal structure of the return stack,
such knowledge is not required of a user of compliant Forth systems.

<P>

<hr>
<a name=A.13.6>
<H3>A.13.6 Glossary</H3>
</a>



<hr>
<a name=A.13.6.1.2295>A.13.6.1.2295 TO</A>
<P>

Typical use:    <code>x TO name</code>

<P>
<code>
See:  <a href=dpansa6.htm#A.6.2.2295>A.6.2.2295 TO</A>
</code>
<P>

<hr>
<a name=A.13.6.2.1795>A.13.6.2.1795 LOCALS|</A>
<P>

A possible implementation of this word and an example of usage is given in
<a href=dpansa13.htm#A.13>A.13</a>, 
above.  It is intended as an example only; any implementation yielding
the described semantics is acceptable.

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa14.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa14.htm/   845512740   500   0     100644  1161      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa13.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa15.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.14>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.14 The optional Memory-Allocation word set</H2>

The Memory-Allocation word set provides a means for acquiring memory
other than the contiguous data space that is allocated by 
<a href=dpans6.htm#6.1.0710>ALLOT</a>.  In
many operating system environments it is inappropriate for a process to
pre-allocate large amounts of contiguous memory (as would be necessary
for the use of ALLOT).  The Memory-Allocation word set can acquire
memory from the system at any time, without knowing in advance the
address of the memory that will be acquired.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa15.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa15.htm/   845512740   500   0     100644  7339      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa14.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa16.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.15>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.15 The optional Programming-Tools word set</H2>

These words have been in widespread common use since the earliest Forth
systems.

<P>

Although there are environmental dependencies intrinsic to programs
using an assembler, virtually all Forth systems provide such a
capability.  Insofar as many Forth programs are intended for real-time
applications and are intrinsically non-portable for this reason, the
Technical Committee believes that providing a standard window into
assemblers is a useful contribution to Forth programmers.

<P>

Similarly, the programming aids 
<a href=dpans15.htm#15.6.1.1280>DUMP</a>, 
etc., are valuable tools even
though their specific formats will differ between CPUs and Forth
implementations.  These words are primarily intended for use by the
programmer, and are rarely invoked in programs.

<P>

One of the original aims of Forth was to erase the boundary between
<B>user</B> and <B>programmer</B> - to give all possible power to anyone
who had occasion to use a computer.  Nothing in the above labeling or
remarks should be construed to mean that this goal has been abandoned.

<P>

<hr>
<A name=A.15.6>
<H3>A.15.6 Glossary</H3>
</a>



<hr>
<A name=A.15.6.1.0220>A.15.6.1.0220 .S</A>
<P>

.S is a debugging convenience found on almost all Forth systems.  It is
universally mentioned in Forth texts.

<P>

<hr>
<A name=A.15.6.1.2194>A.15.6.1.2194 SEE</A>
<P>

SEE acts as an on-line form of documentation of words, allowing modification
of words by decompiling and regenerating with appropriate changes.

<P>

<hr>
<A name=A.15.6.1.2465>A.15.6.1.2465 WORDS</A>
<P>

WORDS is a debugging convenience found on almost all Forth systems.  It is
universally referred to in Forth texts.

<P>

<hr>
<A name=A.15.6.2.0470>A.15.6.2.0470 ;CODE</A>
<P>

Typical use:    <code>: namex ... &lt;create&gt; ... ;CODE ...</code>

<P>

where namex is a defining word, and &lt;create&gt; is 
<a href=dpans6.htm#6.1.1000>CREATE</a> or any user
defined
word that calls CREATE.

<P>

<hr>
<A name=A.15.6.2.0930>A.15.6.2.0930 CODE</A>
<P>

Some Forth systems implement the assembly function by adding an
<a href=dpans15.htm#15.6.2.0740>ASSEMBLER</a> 
word list to the search order, using the text interpreter to
parse a postfix assembly language with lexical characteristics similar
to Forth source code.  Typically, in such systems, assembly ends when a
word END-CODE is interpreted.

<P>

<hr>
<A name=A.15.6.2.1015>A.15.6.2.1015 CS-PICK</A>
<P>

The intent is to reiterate a dest on the control-flow stack so that it can be
resolved more than once.  For example:

<PRE>
\ Conditionally transfer control to beginning of loop
\ This is similar in spirit to C's "continue" statement.

: ?REPEAT  ( dest -- dest ) \ Compilation
           ( flag -- )      \ Execution
    0 CS-PICK   POSTPONE UNTIL
; IMMEDIATE

: XX  ( -- ) \ Example use of ?REPEAT
    BEGIN
      ...
    flag ?REPEAT  ( Go back to BEGIN if flag is false )
      ...
    flag ?REPEAT  ( Go back to BEGIN if flag is false )
      ...
    flag UNTIL    ( Go back to BEGIN if flag is false )
    ...
;
</PRE>

<P>

<hr>
<A name=A.15.6.2.1020>A.15.6.2.1020 CS-ROLL</A>
<P>

The intent is to modify the order in which the origs and dests on the
control-flow stack are to be resolved by subsequent control-flow words.  For
example, 
<a href=dpans6.htm#6.1.2430>WHILE</a> could be implemented in terms of 
<a href=dpans6.htm#6.1.1700>IF</a> and CS-ROLL, as follows:

<PRE>
: WHILE  ( dest -- orig dest )   POSTPONE IF  1 CS-ROLL ; IMMEDIATE
</PRE>
<P>

<hr>
<A name=A.15.6.2.1580>A.15.6.2.1580 FORGET</A>
<P>

Typical use:     <code>... FORGET name ...</code>

<P>

FORGET assumes that all the information needed to restore the dictionary to
its previous state is inferable somehow from the forgotten word.  While this
may be true in simple linear dictionary models, it is difficult to implement
in other Forth systems; e.g., those with multiple address spaces.  For
example, if Forth is embedded in ROM, how does FORGET know how much RAM to
recover when an array is forgotten?  A general and preferred solution is
provided by 
<a href=dpans6.htm#6.2.1850>MARKER</a>.

<P>

<hr>
<A name=A.15.6.2.2531>A.15.6.2.2531 [ELSE]</A>
<P>

Typical use:    <code>... flag [IF] ... [ELSE] ... [THEN] ...</code>

<P>

<hr>
<A name=A.15.6.2.2532>A.15.6.2.2532 [IF]</A>
<P>

Typical use:    <code>... flag [IF] ... [ELSE] ... [THEN] ...</code>

<P>

<hr>
<A name=A.15.6.2.2533>A.15.6.2.2533 [THEN]</A>
<P>

Typical use:    <code>... flag [IF] ... [ELSE] ... [THEN] ...</code>

<P>

Software that runs in several system environments often contains some
source code that is environmentally dependent. Conditional compilation - the 
selective inclusion or exclusion of portions of the source code at
compile time - is one technique that is often used to assist in the
maintenance of such source code.
<P>

Conditional compilation is sometimes done with <B>smart comments</B> -
definitions that either skip or do not skip the remainder of the line
based on some test.  For example:

<PRE>
\ If 16-Bit? contains TRUE, lines preceded by 16BIT\
\ will be skipped. Otherwise, they will not be skipped.

VARIABLE 16-BIT?

: 16BIT\  ( -- )  16-BIT? @  IF  POSTPONE \  THEN ;  IMMEDIATE
</PRE>

<P>

This technique works on a line by line basis, and is good for short,
isolated variant code sequences.

<P>

More complicated conditional compilation problems suggest a nestable
method that can encompass more than one source line at a time.  The
words included in the ANS Forth optional Programming tools extensions
word set are useful for this purpose.  The implementation given below
works with any input source (keyboard, 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>, 
<a href=dpans7.htm#7.6.1.0800>BLOCK</a>, or text file).

<PRE>
: [ELSE]  ( -- )
    1 BEGIN                               \ level
      BEGIN
        BL WORD COUNT  DUP  WHILE         \ level adr len
        2DUP  S" [IF]"  COMPARE 0=
        IF                                \ level adr len
          2DROP 1+                        \ level'
        ELSE                              \ level adr len
          2DUP  S" [ELSE]"
          COMPARE 0= IF                   \ level adr len
             2DROP 1- DUP IF 1+ THEN      \ level'
          ELSE                            \ level adr len
            S" [THEN]"  COMPARE 0= IF     \ level
              1-                          \ level'
            THEN
          THEN
        THEN ?DUP 0=  IF EXIT THEN        \ level'
      REPEAT  2DROP                       \ level
    REFILL 0= UNTIL                       \ level
    DROP
;  IMMEDIATE

: [IF]  ( flag -- )
0= IF POSTPONE [ELSE] THEN ;  IMMEDIATE

: [THEN]  ( -- )  ;  IMMEDIATE
</PRE>

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa16.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa16.htm/   845512740   500   0     100644  7876      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa15.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa17.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.16>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>


<H2>A.16 The optional Search-Order word set</H2>

Search-order specification and control mechanisms vary widely.  The
FIG-Forth, Forth-79, polyFORTH, and Forth-83 vocabulary and search order
mechanisms are all mutually incompatible.  The complete list of
incompatible mechanisms, in use or proposed, is much longer.  The
<a href=dpans16.htm#16.6.2.0715>ALSO</a>/<a href=dpans16.htm#16.6.2.1965>ONLY</a> 
scheme described in a Forth-83 Experimental Proposal has
substantial community support.  However, many consider it to be
fundamentally flawed, and oppose it vigorously.

<P>

Recognizing this variation, this Standard specifies a new
<B>primitive</B> set of tools from which various schemes may be
constructed.  This primitive search-order word set is intended to be a
portable <B>construction set</B> from which search-order words may be
built, rather than a user interface.  ALSO/ONLY or the various
<B>vocabulary</B> schemes supported by the major Forth vendors can be
defined in terms of the primitive search-order word set.

<P>

The encoding for word list identifiers wid might be a small-integer
index into an array of word-list definition records, the data-space
address of such a record, a user-area offset, the execution token of a
Forth-83 style sealed vocabulary, the link-field address of the first
definition in a word list, or anything else.  It is entirely up to the
system implementor.

<P>

In some systems the interpretation of numeric literals is controlled by
including <B>pseudo word lists</B> that recognize numbers at the end of
the search order.  This technique is accommodated by the <B>default
search order</B> behavior of 
<a href=dpans16.htm#16.6.1.2197>SET-ORDER</a> 
when given an argument of -1.  In
a system using the traditional implementation of ALSO/ONLY , the minimum
search order would be equivalent to the word ONLY.

<P>

There has never been a portable way to restore a saved search order.
F83 (not Forth-83) introduced the word 
<a href=dpans16.htm#16.6.2.2037>PREVIOUS</a>, which almost made it
possible to <B>unload</B> the search order by repeatedly executing the
phrase <b><code>CONTEXT @ PREVIOUS</code></b>.  
The search order could be <B>reloaded</B> by
repeating 
<b><code>ALSO CONTEXT !</code></b>.  
Unfortunately there was no portable way to
determine how many word lists were in the search order.

<P>

ANS Forth has removed the word CONTEXT because in many systems its
contents refer to more than one word list, compounding portability
problems.

<P>

Note that : 
(<a href=dpans6.htm#6.1.0450>colon</a>) 
no longer affects the search order.  The previous
behavior, where the compilation word list replaces the first word list
of the search order, can be emulated with the following redefinition of
: (colon).

<PRE>
: :  GET-ORDER SWAP DROP  GET-CURRENT  SWAP SET-ORDER  : ;
</PRE>
<P>



<hr>
<A name=A.16.2>
<H3>A.16.2 Additional terms</H3>
</a>

<DL>
<DT><b>search order</b>
<DD>Note that the use of the term <B>list</B> does not necessarily imply
implementation as a linked list.</DL>

<P>


<hr>
<A name=A.16.3.3>
<H4>A.16.3.3 Finding definition names</H4>
</a>

In other words, the following is not guaranteed to work:

<PRE>
: FOO  ... [ ... SET-CURRENT ] ... RECURSE ... ;  IMMEDIATE
</PRE>

<a href=dpans6.htm#6.1.2120>RECURSE</a>, 
; (<a href=dpans6.htm#6.1.0460>semicolon</a>), and 
<a href=dpans6.htm#6.1.1710>IMMEDIATE</a> 
may or may not need information stored
in the compilation word list.

<P>


<hr>
<A name=A.16.6>
<H3>A.16.6 Glossary</H3>
</a>



<hr>
<A name=A.16.6.1.2192>A.16.6.1.2192 SEARCH-WORDLIST</A>
<P>

The string argument to SEARCH-WORDLIST is represented by c-addr u,
rather than by just c-addr as with 
<a href=dpans6.htm#6.1.1550>FIND</a>.  
The committee wishes to
establish c-addr u as the preferred representation of a string on the
stack, and has adopted that representation for all new functions that
accept string arguments.  While this decision may cause the
implementation of SEARCH-WORDLIST to be somewhat more difficult in
existing systems, the committee feels that the additional difficulty is
minor.

<P>

When SEARCH-WORDLIST fails to find the word, it does not return the
string, as does FIND.  This is in accordance with the general principle
that Forth words consume their arguments.

<P>

<hr>
<A name=A.16.6.2.0715>A.16.6.2.0715 ALSO</A>
<P>

Here is an implementation of 
ALSO/<a href=dpans16.htm#16.6.2.1965>ONLY</a> 
in terms of the primitive
search-order word set.


<PRE>
WORDLIST CONSTANT ROOT   ROOT SET-CURRENT

: DO-VOCABULARY  ( -- ) \ Implementation factor
    DOES>  @ >R           (  ) ( R: widnew )
     GET-ORDER  SWAP DROP ( wid1 ... widn-1 n )
     R> SWAP SET-ORDER
;

: DISCARD  ( x1 .. xu u - ) \ Implementation factor
   0 ?DO DROP LOOP          \ DROP u+1 stack items
;

CREATE FORTH  FORTH-WORDLIST , DO-VOCABULARY

: VOCABULARY  ( name -- )  WORDLIST CREATE ,  DO-VOCABULARY ;

: ALSO  ( -- )  GET-ORDER  OVER SWAP 1+ SET-ORDER ;

: PREVIOUS  ( --  )  GET-ORDER  SWAP DROP 1- SET-ORDER ;

: DEFINITIONS  ( -- )  GET-ORDER  OVER SET-CURRENT DISCARD ;

: ONLY ( -- )  ROOT ROOT  2 SET-ORDER ;

\ Forth-83 version; just removes ONLY
: SEAL  ( -- )  GET-ORDER 1- SET-ORDER DROP ;

\ F83 and F-PC version; leaves only CONTEXT
: SEAL  ( -- )  GET-ORDER OVER 1 SET-ORDER DISCARD ;
</PRE>

<P>

The preceding definition of ONLY in terms of a <B>ROOT</B> word list
follows F83 usage, and assumes that the default search order just
includes ROOT and 
<a href=dpans16.htm#16.6.2.1590>FORTH</a>.  
A more portable definition of FORTH and ONLY,
without the assumptions, is:

<PRE>
&lt;omit the  ... WORDLIST CONSTANT ROOT ... line&gt;

CREATE FORTH GET-ORDER OVER , DISCARD DO-VOCABULARY

: ONLY  ( -- )  -1 SET-ORDER ;
</PRE>

<P>

Here is a simple implementation of 
<a href=dpans16.htm#16.6.1.1647>GET-ORDER</a> and 
<a href=dpans16.htm#16.6.1.2197>SET-ORDER</a>, including a
corresponding definition of 
<a href=dpans6.htm#6.1.1550>FIND</a>.  The implementations of 
<a href=dpans16.htm#16.6.1.2460>WORDLIST</a>,
<a href=dpans16.htm#16.6.1.2192>SEARCH-WORDLIST</a>, 
<a href=dpans16.htm#16.6.1.1643>GET-CURRENT</a> and 
<a href=dpans16.htm#16.6.1.2195>SET-CURRENT</a> 
depend on system details
and are not given here.

<PRE>
16 CONSTANT #VOCS

VARIABLE #ORDER

CREATE CONTEXT  #VOCS CELLS ALLOT

: GET-ORDER  ( -- wid1 .. widn n )
    #ORDER @ 0 ?DO
      #ORDER @  I - 1- CELLS CONTEXT + @
    LOOP
    #ORDER @
;

: SET-ORDER  ( wid1 .. widn n -- )
    DUP -1 = IF
      DROP  &lt;push system default word lists and n&gt;
    THEN
    DUP #ORDER !
    0 ?DO  I CELLS CONTEXT + ! LOOP
;

: FIND  ( c-addr -- c-addr 0 | w 1 | w -1 )
    0                     ( c-addr 0 )
    #ORDER @ 0 ?DO
      OVER COUNT          ( c-addr 0 c-addr' u )
      I CELLS CONTEXT + @ ( c-addr 0 c-addr' u wid)
      SEARCH-WORDLIST     ( c-addr 0; 0 | w 1 | w -1 )
      ?DUP IF             ( c-addr 0; w 1 | w -1 )
        2SWAP 2DROP LEAVE ( w 1 | w -1 )
      THEN                ( c-addr 0 )
    LOOP                  ( c-addr 0 | w 1 | w -1 )
;
</PRE>

<P>

In an implementation where the dictionary search mechanism uses a hash
table or lookup cache to reduce the search time, SET-ORDER might need to
reconstruct the hash table or flush the cache.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa17.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa17.htm/   845512680   500   0     100644  2906      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa16.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansb.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.17>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.17 The optional String word set</H2>



<hr>
<A name=A.17.6>
<H3>A.17.6 Glossary</H3>
</a>



<hr>
<A name=A.17.6.1.0245>A.17.6.1.0245 /STRING</A>
<P>

/STRING is used to remove or add characters relative to the <B>left</B>
end of the character string.  Positive values of n will exclude
characters from the string while negative values of n will include
characters to the left of the string.  /STRING is a natural factor of
<a href=dpans6.htm#6.1.2450>WORD</a> 
and commonly available.

<P>

<hr>
<A name=A.17.6.1.0910>A.17.6.1.0910 CMOVE</A>
<P>

If c-addr2 lies within the source region (i.e., when c-addr2 is not less
than c-addr1 and c-addr2 is less than the quantity c-addr1 u 
<a href=dpans6.htm#6.1.0898>CHARS</a> +),
memory propagation occurs.

<P>

Typical
use:    Assume a character string at address 100: <B>ABCD</B>.  Then after


<PRE>
	100 DUP  CHAR+  3 CMOVE
</PRE>

<P>

the string at address 100 is <B>AAAA</B>.

<P>

Rationale
for CMOVE and 
<a href=dpans17.htm#17.6.1.0920>CMOVE&gt;</a> follows 
<a href=dpans6.htm#6.1.1900>MOVE</a>.

<P>

<hr>
<A name=A.17.6.1.0920>A.17.6.1.0920 CMOVE&gt;</A>
<P>

If c-addr1 lies within the destination region (i.e., when c-addr1 is
greater than or equal to c-addr2 and c-addr2 is less than the quantity
c-addr1 u 
<a href=dpans6.htm#6.1.0898>CHARS</a> +), memory propagation occurs.

<P>

Typical use:    Assume a character string at address 100: <B>ABCD</B>.
Then after


<PRE>
	100 DUP CHAR+ SWAP 3 CMOVE>
</PRE>

<P>

the string at address 100 is <B>DDDD</B>.

<P>

<hr>
<A name=A.17.6.1.0935>A.17.6.1.0935 COMPARE</A>
<P>

Existing Forth systems perform string comparison operations using words that
differ in spelling, input and output arguments, and case sensitivity.  One in
widespread use was chosen.

<P>

<hr>
<A name=A.17.6.1.2191>A.17.6.1.2191 SEARCH</A>
<P>

Existing Forth systems perform string searching operations using words that
differ in spelling, input and output arguments, and case sensitivity.  One in
widespread use was chosen.

<P>

<hr>
<A name=A.17.6.1.2212>A.17.6.1.2212 SLITERAL</A>
<P>

The current functionality of 
<a href=dpans6.htm#6.1.2165>6.1.2165</a> S" may be provided by the following
definition:

<PRE>
: S" ( "ccc&lt;quote&gt;" -- )
    [CHAR] " PARSE   POSTPONE SLITERAL ; IMMEDIATE

</PRE>
<P>


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansb.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa2.htm/    845512680   500   0     100644  3079      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa1.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa3.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.2>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>


<H2>A.2 Terms and notation</H2>


<hr>
<a name=A.2.1>
<H3>A.2.1 Definitions of terms</H3>
</a>

<DL>
<DT><b>ambiguous condition</b>
<DD>The response of a Standard System to an ambiguous condition is left to
the discretion of the implementor.  A Standard System need not
explicitly detect or report the occurrence of ambiguous conditions.
<p>
<DT><b>cross compiler</b>
<DD>Cross-compilers may be used to prepare a program for execution in an
embedded system, or may be used to generate Forth kernels either for the
same or a different run-time environment.
<p>
<DT><b>data field</b>
<DD>In earlier standards, data fields were known as <B>parameter fields</B>.
<P>

On subroutine threaded Forth systems, everything is object code.  There
are no traditional code or data fields.  Only a word defined by 
<a href=dpans6.htm#6.1.1000>CREATE</a>
or by a word that calls 
CREATE has a data field.  Only a data field
defined via CREATE can be manipulated portably.
<p>
<DT><b>word set</b>
<DD>This Standard recognizes that some functions, while useful in certain
application areas, are not sufficiently general to justify requiring
them in all Forth systems.  Further, it is helpful to group Forth words
according to related functions.  These issues are dealt with using the
concept of word sets.

<P>

The <B>Core</B> word set contains the essential body of words in a Forth
system.  It is the only <B>required</B> word set.  Other word sets
defined in this Standard are optional additions to make it possible to
provide Standard Systems with tailored levels of functionality.</DL>

<P>

<hr>
<a name=A.2.2>
<H3>A.2.2 Notation</H3>
</a>


<hr>
<a name=A.2.2.2>
<H4>A.2.2.2 Stack notation</H4>
</a>

The use of -sys, orig, and dest data types in stack effect diagrams
conveys two pieces of information.  First, it warns the reader that many
implementations use the data stack in unspecified ways for those
purposes, so that items underneath on either the control-flow or data
stacks are unavailable.  Second, in cases where orig and dest are used,
explicit pairing rules are documented on the assumption that all systems
will implement that model so that its results are equivalent to
employment of some stack, and that in fact many implementations do use
the data stack for this purpose.  However, nothing in this Standard
requires that implementations actually employ the data stack (or any
other) for this purpose so long as the implied behavior of the model is
maintained.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa3.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa3.htm/    851247420   500   0     100644  44340     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa2.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa4.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.3>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>A.3 Usage requirements</H1>

Forth systems are unusually simple to develop, in comparison with
compilers for more conventional languages such as C.  In addition to
Forth systems supported by vendors, public-domain implementations and
implementation guides have been widely available for nearly twenty
years, and a large number of individuals have developed their own Forth
systems.  As a result, a variety of implementation approaches have
developed, each optimized for a particular platform or target market.

<P>

The X3J14 Technical Committee has endeavored to accommodate this
diversity by constraining implementors as little as possible, consistent
with a goal of defining a standard interface between an underlying Forth
System and an application program being developed on it.

<P>

Similarly, we will not undertake in this section to tell you how to
implement a Forth System, but rather will provide some guidance as to
what the minimum requirements are for systems that can properly claim
compliance with this Standard.

<P>

<hr>
<a name=A.3.1>
<H2>A.3.1 Data-types</H2>
</a>

Most computers deal with arbitrary bit patterns.  There is no way to
determine by inspection whether a cell contains an address or an
unsigned integer.  The only meaning a datum possesses is the meaning
assigned by an application.

<P>

When data are operated upon, the meaning of the result depends on the
meaning assigned to the input values.  Some combinations of input values
produce meaningless results: for instance, what meaning can be assigned
to the arithmetic sum of the ASCII representation of the character
<B>A</B> and a 
<a href=dpans6.htm#6.2.2298>TRUE</a> 
flag? The answer may be <B>no meaning</B>; or
alternatively, that operation might be the first step in producing a
checksum.  Context is the determiner.

<P>

The discipline of circumscribing meaning which a program may assign to
various combinations of bit patterns is sometimes called data typing.
Many computer languages impose explicit data typing and have compilers
that prevent ill-defined operations.

<P>

Forth rarely explicitly imposes data-type restrictions.  Still, data
types implicitly do exist, and discipline is required, particularly if
portability of programs is a goal.  In Forth, it is incumbent upon the
programmer (rather than the compiler) to determine that data are
accurately typed.

<P>

This section attempts to offer guidance regarding de facto data typing
in Forth.

<P>

<hr>
<a name=A.3.1.2>
<H3>A.3.1.2 Character types</H3>
</a>

The correct identification and proper manipulation of the character data
type is beyond the purview of Forth's enforcement of data type by means
of stack depth.  Characters do not necessarily occupy the entire width
of their single stack entry with meaningful data.  While the distinction
between signed and unsigned character is entirely absent from the formal
specification of Forth, the tendency in practice is to treat characters
as short positive integers when mathematical operations come into play.

<P>

<dl>
a) Standard Character Set

<P>

<dl>
1) The storage unit for the character data type 
(<a href=dpans6.htm#6.1.0870>C@</a>, 
<a href=dpans6.htm#6.1.0850>C!</a>, 
<a href=dpans6.htm#6.1.1540>FILL</a>, etc.) must be
able to contain unsigned numbers from 0 through 255.

<P>

2) An implementation is not required to restrict character storage to
that range, but a Standard Program without environmental dependencies
cannot assume the ability to store numbers outside that range in a
<B>char</B> location.

<P>

3) The allowed number representations are two's-complement,
one's-complement, and signed-magnitude.  Note that all of these number
systems agree on the representation of positive numbers.

<P>

4) Since a <B>char</B> can store small positive numbers and since the
character data type is a sub-range of the unsigned integer data type, C!
must store the n least-significant bits of a cell (8 <= n <= bits/cell).
Given the enumeration of allowed number representations and their known
encodings, 
<B><code>TRUE xx C! xx C@</code></B> must leave a stack item with some
number of bits set, which will thus will be accepted as non-zero by 
<a href=dpans6.htm#6.1.1700>IF</a>.

<P>

5) For the purposes of input 
(<a href=dpans6.htm#6.1.1750>KEY</a>, 
<a href=dpans6.htm#6.1.0695>ACCEPT</a>, 
etc.) and output 
(<a href=dpans6.htm#6.1.1320>EMIT</a>, 
<a href=dpans6.htm#6.1.2310>TYPE</a>,
etc.), the encoding between numbers and human-readable symbols is
ISO646/IRV (ASCII) within the range from 32 to 126 (space to ~).  EBCDIC
is out (most <B>EBCDIC</B> computer systems support ASCII too).  Outside
that range, it is up to the implementation.  The obvious implementation
choice is to use ASCII control characters for the range from 0 to 31, at
least for the <B>displayable</B> characters in that range (TAB, RETURN,
LINEFEED, FORMFEED).  However, this is not as clear-cut as it may seem,
because of the variation between operating systems on the treatment of
those characters.  For example, some systems TAB to 4 character
boundaries, others to 8 character boundaries, and others to preset tab
stops.  Some systems perform an automatic linefeed after a carriage
return, others perform an automatic carriage return after a linefeed,
and others do neither.

<P>

The codes from 128 to 255 may eventually be standardized, either
formally or informally, for use as international characters, such as the
letters with diacritical marks found in many European languages.  One
such encoding is the 8-bit ISO Latin-1 character set.  The computer
marketplace at large will eventually decide which encoding set of those
characters prevails.  For Forth implementations running under an
operating system (the majority of those running on standard platforms
these days), most Forth implementors will probably choose to do whatever
the system does, without performing any remapping within the domain of
the Forth system itself.

<P>

6) A Standard Program can depend on the ability to receive any character
in the range 32 ...  126 through KEY, and similarly to display the same
set of characters with EMIT.  If a program must be able to receive or
display any particular character outside that range, it can declare an
environmental dependency on the ability to receive or display that
character.

<P>

7) A Standard Program cannot use control characters in definition names.
However, a Standard System is not required to enforce this prohibition.
Thus, existing systems that currently allow control characters in words
names from 
<a href=dpans7.htm#7.6.1.0790>BLOCK</a> 
source may continue to allow them, and programs running
on those systems will continue to work.  In text file source, the
parsing action with space as a delimiter (e.g., 
<a href=dpans6.htm#6.1.0770>BL</a> 
<a href=dpans6.htm#6.1.2450>WORD</a>) treats control
characters the same as spaces.  This effectively implies that you cannot
use control characters in definition names from text-file source, since
the text interpreter will treat the control characters as delimiters.
Note that this <B>control-character folding</B> applies only when space
is the delimiter, thus the phrase 
<code><B>CHAR ) WORD</B></code> may collect a
string containing control characters.
</dl>
<P>

b) Storage and retrieval
<P>

<dl>
Characters are transferred from the data stack to memory by C! and from
memory to the data stack by C@.  A number of lower-significance bits
equivalent to the implementation-dependent width of a character are
transferred from a popped data stack entry to an address by the action
of C! without affecting any bits which may comprise the
higher-significance portion of the cell at the destination address;
however, the action of C@ clears all higher-significance bits of the
data stack entry which it pushes that are beyond the
implementation-dependent width of a character (which may include
implementation-defined display information in the higher-significance
bits).  The programmer should keep in mind that operating upon arbitrary
stack entries with words intended for the character data type may result
in truncation of such data.
</dl>
<P>

c) Manipulation on the stack
<P>

<dl>
In addition to C@ and C!, characters are moved to, from and upon the
data stack by the following words:

<P>

<code>
<a href=dpans6.htm#6.1.0580>&gt;R</a>  
<a href=dpans6.htm#6.1.0630>?DUP</a>  
<a href=dpans6.htm#6.1.1260>DROP</a>  
<a href=dpans6.htm#6.1.1290>DUP</a>  
<a href=dpans6.htm#6.1.1990>OVER</a>  
<a href=dpans6.htm#6.2.2030>PICK</a>  
<a href=dpans6.htm#6.1.2060>R&gt;</a>  
<a href=dpans6.htm#6.1.2070>R@</a>  
<a href=dpans6.htm#6.2.2150>ROLL</a>  
<a href=dpans6.htm#6.1.2160>ROT</a>  
<a href=dpans6.htm#6.1.2260>SWAP</a>
</code>
</dl>
<P>

d) Additional operations
<P>

<dl>
The following mathematical operators are valid for character data:

<P>

<code>
<a href=dpans6.htm#6.1.0120>+</a>  
<a href=dpans6.htm#6.1.0160>-</a>  
<a href=dpans6.htm#6.1.0090>*</a>  
<a href=dpans6.htm#6.1.0230>/</a>  
<a href=dpans6.htm#6.1.0240>/MOD</a>  
<a href=dpans6.htm#6.1.1890>MOD</a>
</code>
<P>

The following comparison and bitwise operators may be valid for
characters, keeping in mind that display information cached in the most
significant bits of characters in an implementation-defined fashion may
have to be masked or otherwise dealt with:

<P>

<code>
<a href=dpans6.htm#6.1.0720>AND</a>  
<a href=dpans6.htm#6.1.1980>OR</a>  
<a href=dpans6.htm#6.1.0540>&gt;</a>  
<a href=dpans6.htm#6.1.0480>&lt;</a>  
<a href=dpans6.htm#6.2.2350>U&gt;</a>  
<a href=dpans6.htm#6.1.2340>U&lt;</a>  
<a href=dpans6.htm#6.1.0530>=</a>  
<a href=dpans6.htm#6.2.0500>&lt;&gt;</a>  
<a href=dpans6.htm#6.1.0270>0=</a>  
<a href=dpans6.htm#6.2.0260>0&lt;&gt;</a>  
<a href=dpans6.htm#6.1.1870>MAX</a>  
<a href=dpans6.htm#6.1.1880>MIN</a> 
<a href=dpans6.htm#6.1.1805>LSHIFT</a> 
<a href=dpans6.htm#6.1.2162>RSHIFT</a>
</code>

</dl>
</dl>
<P>


<hr>
<a name=A.3.1.3>
<h3>A.3.1.3   Single-cell types</h3>
</a>
<P>

A single-cell stack entry viewed without regard to typing is the
fundamental data type of Forth.  All other data types are actually
represented by one or more single-cell stack entries.

<P>

<dl>
a) Storage and retrieval
<P>


<dl>
Single-cell data are transferred from the stack to memory by 
<a href=dpans6.htm#6.1.0010>!</a>; from
memory to the stack by 
<a href=dpans6.htm#6.1.0650>@</a>.  
All bits are transferred in both directions
and no type checking of any sort is performed, nor does the Standard
System check that a memory address used by ! or @ is properly aligned or
properly sized to hold the datum thus transferred.
</dl>
<P>

b) Manipulation on the stack
<P>

<dl>
Here is a selection of the most important words which move single-cell
data to, from and upon the data stack:

<P>

<code>
!  
@  
<a href=dpans6.htm#6.1.0580>&gt;R</a>  
<a href=dpans6.htm#6.1.0630>?DUP</a>  
<a href=dpans6.htm#6.1.1260>DROP</a>  
<a href=dpans6.htm#6.1.1290>DUP</a>  
<a href=dpans6.htm#6.1.1990>OVER</a>  
<a href=dpans6.htm#6.2.2030>PICK</a>  
<a href=dpans6.htm#6.1.2060>R&gt;</a>  
<a href=dpans6.htm#6.1.2070>R@</a>  
<a href=dpans6.htm#6.2.2150>ROLL</a>  
<a href=dpans6.htm#6.1.2160>ROT</a>  
<a href=dpans6.htm#6.1.2260>SWAP</a>
</code>
</dl>
<P>

c) Comparison operators
<P>

<dl>
The following comparison operators are universally valid for one or more
single cells:

<P>

<code>
<a href=dpans6.htm#6.1.0530>=</a>  
<a href=dpans6.htm#6.2.0500>&lt;&gt;</a>  
<a href=dpans6.htm#6.1.0270>0=</a>  
<a href=dpans6.htm#6.2.0260>0&lt;&gt;</a>
</code>
<P>
</dl>
</dl>

<hr>
<a name=A.3.1.3.1>
<H4>A.3.1.3.1 Flags</H4>
</a>

A 
<a href=dpans6.htm#6.2.1485>FALSE</a> 
flag is a single-cell datum with all bits unset, and a 
<a href=dpans6.htm#6.2.2298>TRUE</a> 
flag
is a single-cell datum with all bits set.  While Forth words which test
flags accept any non-null bit pattern as true, there exists the concept
of the well-formed flag.  If an operation whose result is to be used as
a flag may produce any bit-mask other than TRUE or FALSE, the
recommended discipline is to convert the result to a well-formed flag by
means of the Forth word 
<a href=dpans6.htm#6.2.0260>0&lt;&gt;</a> 
so that the result of any subsequent logical
operations on the flag will be predictable.

<P>

In addition to the words which move, fetch and store single-cell items,
the following words are valid for operations on one or more flag data
residing on the data stack:

<P>

<code>
<a href=dpans6.htm#6.1.0720>AND</a>  
<a href=dpans6.htm#6.1.1980>OR</a>  
<a href=dpans6.htm#6.1.2490>XOR</a>  
<a href=dpans6.htm#6.1.1720>INVERT</a>
</code>
<P>

<hr>
<a name=A.3.1.3.2>
<h4>A.3.1.3.2 Integers</h4>
</a>
<p>

Given the same number of bits, unsigned integers usually represent twice
the number of absolute values representable by signed integers.

<P>

A single-cell datum may be treated by a Standard Program as an unsigned
integer.  Moving and storing such data is performed as for any
single-cell data.  In addition, the following mathematical and
comparison operators are valid for single-cell unsigned integers:

<P>

<code>
<a href=dpans6.htm#6.1.2360>UM*</a>  
<a href=dpans6.htm#6.1.2370>UM/MOD</a>  
<a href=dpans6.htm#6.1.0120>+</a>  
<a href=dpans6.htm#6.1.0130>+!</a>  
<a href=dpans6.htm#6.1.0160>-</a>  
<a href=dpans6.htm#6.1.0290>1+</a>  
<a href=dpans6.htm#6.1.0300>1-</a>  
<a href=dpans6.htm#6.1.0090>*</a>  
<a href=dpans6.htm#6.1.2340>U&lt;</a>  
<a href=dpans6.htm#6.2.2350>U&gt;</a>
</code>
<P>


<hr>
<a name=A.3.1.3.3>
<H4>A.3.1.3.3 Addresses</H4>
</a>

An address is uniquely represented as a single cell unsigned number and can be
treated as such when being moved to, from, or upon the stack.  Conversely,
each unsigned number represents a unique address (which is not necessarily an
address of accessible memory).  This one-to-one relationship between addresses
and unsigned numbers forces an equivalence between address arithmetic and the
corresponding operations on unsigned numbers.

<P>

Several operators are provided specifically for address arithmetic:
<P>

<code>
<a href=dpans6.htm#6.1.0897>CHAR+</a>  
<a href=dpans6.htm#6.1.0898>CHARS</a>  
<a href=dpans6.htm#6.1.0880>CELL+</a>  
<a href=dpans6.htm#6.1.0890>CELLS</a>
</code>
<P>

and, if the floating-point word set is present:
<P>

<code>
<a href=dpans12.htm#12.6.1.1555>FLOAT+</a>  
<a href=dpans12.htm#12.6.1.1556>FLOATS</a>  
<a href=dpans12.htm#12.6.2.2207>SFLOAT+</a>  
<a href=dpans12.htm#12.6.2.2208>SFLOATS</a>  
<a href=dpans12.htm#12.6.2.1208>DFLOAT+</a>  
<a href=dpans12.htm#12.6.2.1209>DFLOATS</a>
</code>
<P>

A Standard Program may never assume a particular correspondence between
a Forth address and the physical address to which it is mapped.

<P>


<hr>
<a name=A.3.1.3.4>
<H4>A.3.1.3.4 Counted strings</H4>
</a>

The trend in ANS Forth is to move toward the consistent use of the
<B>c-addr u</B> representation of strings on the stack.  The use of the
alternate <B>address of counted string</B> stack representation is
discouraged.  The traditional Forth words 
<a href=dpans6.htm#6.1.2450>WORD</a> and 
<a href=dpans6.htm#6.1.1550>FIND</a> 
continue to use
the <B>address of counted string</B> representation for historical
reasons.  The new word 
<a href=dpans6.htm#6.2.0855>C"</a> 
, added as a porting aid for existing
programs, also uses the counted string representation.

<P>

Counted strings remain useful as a way to store strings in memory.  This
use is not discouraged, but when references to such strings appear on
the stack, it is preferable to use the <B>c-addr u</B> representation.

<P>


<hr>
<a name=A.3.1.3.5>
<H4>A.3.1.3.5 Execution tokens</H4>
</a>

The association between an execution token and a definition is static.
Once made, it does not change with changes in the search order or
anything else.  However it may not be unique, e.g., the phrases

<PRE>
	<b>' 1+</b> 
   and

	<b>' CHAR+</b>
</PRE>
might return the same value.

<P>


<hr>
<a name=A.3.1.4>
<H3>A.3.1.4 Cell-pair types</H3>
</a>

<dl>
a) Storage and retrieval
<P>

<dl>
Two operators are provided to fetch and store cell pairs:

<P>

<code>
<a href=dpans6.htm#6.1.0350>2@</a>  
<a href=dpans6.htm#6.1.0310>2!</a>
</code>
</dl>
<P>

b) Manipulation on the stack
<P>

<dl>
Additionally, these operators may be used to move cell pairs from, to
and upon the stack:

<P>

<code>
<a href=dpans6.htm#6.2.0340>2&gt;R</a>  
<a href=dpans6.htm#6.1.0370>2DROP</a>  
<a href=dpans6.htm#6.1.0380>2DUP</a>  
<a href=dpans6.htm#6.1.0400>2OVER</a>  
<a href=dpans6.htm#6.2.0415>2R&gt;</a>  
<a href=dpans6.htm#6.1.0430>2SWAP</a>  
<a href=dpans8.htm#8.6.2.0420>2ROT</a>
</code>
</dl>
<P>

c) Comparison
<P>

<dl>
The following comparison operations are universally valid for cell
pairs:

<P>

<code>
<a href=dpans8.htm#8.6.1.1120>D=</a>  
<a href=dpans8.htm#8.6.1.1080>D0=</a>
</code>
</dl>
</dl>
<P>


<hr>
<a name=A.3.1.4.1>
<H4>A.3.1.4.1 Double-cell integers</H4>
</a>

If a double-cell integer is to be treated as signed, the following
comparison and mathematical operations are valid:

<P>

<code>
<a href=dpans8.htm#8.6.1.1040>D+</a>  
<a href=dpans8.htm#8.6.1.1050>D-</a>  
<a href=dpans8.htm#8.6.1.1110>D&lt;</a>  
<a href=dpans8.htm#8.6.1.1075>D0&lt;</a>  
<a href=dpans8.htm#8.6.1.1160>DABS</a>  
<a href=dpans8.htm#8.6.1.1210>DMAX</a>  
<a href=dpans8.htm#8.6.1.1220>DMIN</a>  
<a href=dpans8.htm#8.6.1.1230>DNEGATE</a>  
<a href=dpans8.htm#8.6.1.1820>M*/</a>  
<a href=dpans8.htm#8.6.1.1830>M+</a>
</code>
<P>

If a double-cell integer is to be treated as unsigned, the following
comparison and mathematical operations are valid:

<P>

<code>
D+  
D-  
<a href=dpans6.htm#6.1.2370>UM/MOD</a>  
<a href=dpans8.htm#8.6.2.1270>DU&lt;</a>
</code>
<P>


<hr>
<a name=A.3.1.4.2>
<H4>A.3.1.4.2 Character strings</H4>
</a>

See:
<a href=dpansa3.htm#A.3.1.3.4>A.3.1.3.4</a> Counted Strings
<P>


<hr>
<a name=A.3.2>
<H2>A.3.2 The implementation environment</H2>
</a>



<hr>
<a name=A.3.2.1>
<H3>A.3.2.1 Numbers</H3>
</a>

Traditionally, Forth has been implemented on two's-complement machines
where there is a one-to-one mapping of signed numbers to unsigned
numbers - any single cell item can be viewed either as a signed or
unsigned number.  Indeed, the signed representation of any positive
number is identical to the equivalent unsigned representation.  Further,
addresses are treated as unsigned numbers: there is no distinct pointer
type.  Arithmetic ordering on two's complement machines allows + and -
to work on both signed and unsigned numbers.  This arithmetic behavior
is deeply embedded in common Forth practice.  As a consequence of these
behaviors, the likely ranges of signed and unsigned numbers for
implementations hosted on each of the permissible arithmetic
architectures is:

<P>
<pre>
      ---------------------------------------------------------
      Arithmetic architecture  signed numbers  unsigned numbers
      ---------------------------------------------------------
      Two's complement         -n-1 to n       0 to 2n+1
      One's complement         -n to n         0 to n
      Signed magnitude         -n to n         0 to n
      ---------------------------------------------------------
</pre>
<P>

where n is the largest positive signed number.  For all three
architectures, signed numbers in the 0 to n range are bitwise identical
to the corresponding unsigned number.  Note that unsigned numbers on a
signed magnitude machine are equivalent to signed non-negative numbers
as a consequence of the forced correspondence between addresses and
unsigned numbers and of the required behavior of + and -.

<P>

For reference, these number representations may be defined by the way
that 
<a href=dpans6.htm#6.1.1910>NEGATE</a> is implemented:

<P>


<PRE>
two's complement:       : NEGATE  INVERT 1+ ;
one's complement:       : NEGATE  INVERT ;
signed-magnitude:       : NEGATE  HIGH-BIT XOR ;
</PRE>

<P>

where HIGH-BIT is a bit mask with only the most-significant bit set.
Note that all of these number systems agree on the representation of
non-negative numbers.

<P>

Per <A href=dpans3.htm#3.2.1.1>3.2.1.1</A> Internal number 
representation and 
<a href=dpans6.htm#6.1.0270>6.1.0270</a> 0=, the
implementor must ensure that no standard or supported word return
negative zero for any numeric (non-Boolean or flag) result.  Many
existing programmer assumptions will be violated otherwise.

<P>

There is no requirement to implement circular unsigned arithmetic, nor
to set the range of unsigned numbers to the full size of a cell.  There
is historical precedent for limiting the range of u to that of +n, which
is permissible when the cell size is greater than 16 bits.

<P>


<hr>
<A name=A.3.2.1.2>
<H4>A.3.2.1.2 Digit conversion</H4>
</a>

For example, an implementation might convert the characters <B>a</B>
through <B>z</B> identically to the characters <B>A</B> through
<B>Z</B>, or it might treat the characters <B>[</B> through <B>~</B>
as additional digits with decimal values 36 through 71, respectively.

<P>


<hr>
<a name=A.3.2.2>
<H3>A.3.2.2 Arithmetic</H3>
</a>


<hr>
<a name=A.3.2.2.1>
<H4>A.3.2.2.1 Integer division</H4>
</a>

The Forth-79 Standard specifies that the signed division operators 
(<a href=dpans6.htm#6.1.0230>/</a>,
<a href=dpans6.htm#6.1.0240>/MOD</a>, 
<a href=dpans6.htm#6.1.1890>MOD</a>, 
<a href=dpans6.htm#6.1.0110>*/MOD</a>, 
and 
<a href=dpans6.htm#6.1.0100>*/</a>) 
round non-integer quotients towards zero
(symmetric division).  Forth-83 changed the semantics of these operators
to round towards negative infinity (floored division).  Some in the
Forth community have declined to convert systems and applications from
the Forth-79 to the Forth-83 divide.  To resolve this issue, an ANS
Forth system is permitted to supply either floored or symmetric
operators.  In addition, ANS Forth systems must provide a floored
division primitive 
(<a href=dpans6.htm#6.1.1561>FM/MOD</a>), 
a symmetric division primitive 
(<a href=dpans6.htm#6.1.2214>SM/REM</a>),
and a mixed precision multiplication operator 
(<a href=dpans6.htm#6.1.1810>M*</a>).

<P>

This compromise protects the investment made in current Forth
applications; Forth-79 and Forth-83 programs are automatically compliant
with ANS Forth with respect to division.  In practice, the rounding
direction rarely matters to applications.  However, if a program
requires a specific rounding direction, it can use the floored division
primitive FM/MOD or the symmetric division primitive SM/REM to construct
a division operator of the desired flavor.  This simple technique can be
used to convert Forth-79 and Forth-83 programs to ANS Forth without any
analysis of the original programs.

<P>


<hr>
<a name=A.3.2.2.2>
<H4>A.3.2.2.2 Other integer operations</H4>
</a>

Whether underflow occurs depends on the data-type of the result.  For
example, the phrase 
<b><code>1 2 -</code></b> underflows if the result is unsigned and
produces the valid signed result -1.

<P>


<hr>
<a name=A.3.2.3>
<H3>A.3.2.3 Stacks</H3>
</a>

The only data type in Forth which has concrete rather than abstract
existence is the stack entry.  Even this primitive typing Forth only
enforces by the hard reality of stack underflow or overflow.  The
programmer must have a clear idea of the number of stack entries to be
consumed by the execution of a word and the number of entries that will
be pushed back to a stack by the execution of a word.  The observation
of anomalous occurrences on the data stack is the first line of defense
whereby the programmer may recognize errors in an application program.
It is also worth remembering that multiple stack errors caused by
erroneous application code are frequently of equal and opposite
magnitude, causing complementary (and deceptive) results.

<P>

For these reasons and a host of other reasons, the one unambiguous,
uncontroversial, and indispensable programming discipline observed since
the earliest days of Forth is that of providing a stack diagram for all
additions to the application dictionary with the exception of static
constructs such as 
<a href=dpans6.htm#6.1.2410>VARIABLE</a>s and 
<a href=dpans6.htm#6.1.0950>CONSTANT</a>s.

<P>


<hr>
<a name=A.3.2.3.2>
<H4>A.3.2.3.2 Control-flow stack</H4>
</a>

The simplest use of control-flow words is to implement the basic control
structures shown in figure A.1.

<P>

<a name=figure.A.1>*
</a>
<pre>
    ---------------------------------------------------------------
         |                 _____ |               _____ |
        < >-----  IF      |     \|     BEGIN    |     \|     BEGIN
         |      |         |  +-------+          |  +-------+
     +-------+  |         |  |       |          |  |       |
     |       |  |         |  +-------+          |  +-------+
     +-------+  |         |      |              |      |
         | _____|          -----< >    UNTIL     ------      AGAIN
         |/       THEN           |
         |                       |
    ---------------------------------------------------------------
                      Figure A.1 - The basic control-flow patterns.
</pre>
<P>

Figure A.1 - The basic control-flow patterns.
<P>

In control flow every branch, or transfer of control, must terminate at
some destination.  A natural implementation uses a stack to remember the
origin of forward branches and the destination of backward branches.  At
a minimum, only the location of each origin or destination must be
indicated, although other implementation-dependent information also may
be maintained.

<P>

An origin is the location of the branch itself.  A destination is where
control would continue if the branch were taken.  A destination is
needed to resolve the branch address for each origin, and conversely, if
every control-flow path is completed no unused destinations can remain.

<P>

With the addition of just three words 
(<a href=dpans15.htm#15.6.2.0702>AHEAD</a>, 
<a href=dpans15.htm#15.6.2.1020>CS-ROLL</a> and 
<a href=dpans15.htm#15.6.2.1015>CS-PICK</a>), the
basic control-flow words supply the primitives necessary to compile a
variety of transportable control structures.  The abilities required are
compilation of forward and backward conditional and unconditional
branches and compile-time management of branch origins and destinations.
Table A.1 shows the desired behavior.

<P>

The requirement that control-flow words are properly balanced by other
control-flow words makes reasonable the description of a compile-time
implementation-defined control-flow stack.  There is no prescription as
to how the control-flow stack is implemented, e.g., data stack, linked
list, special array.  Each element of the control-flow stack mentioned
above is the same size.

<P>
<a name=table.a.1>*
</a>
<pre>
                 Table A.1 - Compilation behavior of control-flow words
   ---------------------------------------------------------------------------
   at compile time,
   word:    supplies:  resolves:  is used to:
   ---------------------------------------------------------------------------
   IF       orig                  mark origin of forward conditional branch
   THEN                orig       resolve IF or AHEAD
   BEGIN    dest                  mark backward destination
   AGAIN               dest       resolve with backward unconditional branch
   UNTIL               dest       resolve with backward conditional branch
   AHEAD    orig                  mark origin of forward unconditional branch
   CS-PICK                        copy item on control-flow stack
   CS-ROLL                        reorder items on control-flow stack
   --------------------------------------------------------------------------
</pre>
<P>

With these tools, the remaining basic control-structure elements, shown
in 
<a href=dpansa3.htm#figure.a.2>figure A.2</a>, 
can be defined.  The stack notation used here for
immediate words is ( compilation / execution ).

<P>

<PRE>
: WHILE  ( dest -- orig dest / flag -- )
                            \ conditional exit from loops
	POSTPONE IF         \ conditional forward branch
           1 CS-ROLL        \ keep dest on top
; IMMEDIATE


: REPEAT  ( orig dest -- / -- )
                            \ resolve a single WHILE and return to BEGIN
           POSTPONE AGAIN   \ uncond. backward branch to dest
           POSTPONE THEN    \ resolve forward branch from orig
; IMMEDIATE

: ELSE  ( orig1 -- orig2 / -- )
                            \ resolve IF supplying alternate execution
        POSTPONE AHEAD      \ unconditional forward branch orig2
           1 CS-ROLL        \ put orig1 back on top
           POSTPONE THEN    \ resolve forward branch from orig1
; IMMEDIATE
</PRE>

<P>
<a name=figure.a.2>*
</a>
<pre>
     -----------------------------------------------
             |                 _____ |
            < >-----  IF      |     \|        BEGIN
             |      |         |  +-------+
         +-------+  |         |  |       |
         |       |  |         |  +-------+
         +-------+  |         |      |
             | _____|         |     < >-----  WHILE
       _____/ /       ELSE    |      |      |
      |      |                |  +-------+  |
      |  +-------+            |  |       |  |
      |  |       |            |  +-------+  |
      |  +-------+            |      |      |
      |_____ |                |_____/  _____|
            \|        THEN            /       REPEAT
             |                       |
    ----------------------------------------------
    Figure A.2 - Additional basic control-flow patterns.
</pre>
<P>

Forth control flow provides a solution for well-known problems with
strictly structured programming.

<P>

The basic control structures can be supplemented, as shown in the
examples in 
<a href=dpansa3.htm#figure.a.3>figure A.3</a>, 
with additional WHILEs in BEGIN ...  UNTIL and
BEGIN ...  WHILE ...  REPEAT structures.  However, for each additional
WHILE there must be a THEN at the end of the structure.  THEN completes
the syntax with WHILE and indicates where to continue execution when the
WHILE transfers control.  The use of more than one additional WHILE is
possible but not common.  Note that if the user finds this use of THEN
undesirable, an alias with a more likable name could be defined.

<P>

Additional actions may be performed between the control flow word (the
REPEAT or UNTIL) and the THEN that matches the additional WHILE.
Further, if additional actions are desired for normal termination and
early termination, the alternative actions may be separated by the
ordinary Forth ELSE.  The termination actions are all specified after
the body of the loop.

<P>
<a name=figure.a.3>*
</a>
<pre>
    --------------------------------------------------
     _____ |                      _____ |
    |     \|         BEGIN       |     \|        BEGIN
    |  +-------+                 |  +-------+
    |  |       |                 |  |       |
    |  +-------+                 |  +-------+
    |      |                     |      |
    |     < >------  WHILE       |     < >-----  WHILE
    |      |       |             |      |      |
    |  +-------+   |             |  +-------+  |
    |  |       |   |             |  |       |  |
    |  +-------+   |             |  +-------+  |
    |      |       |             |      |      |
    |     < >----  | WHILE        -----< >     | UNTIL
    |      |     | |                    |      |
    |  +-------+ | |                +-------+  |
    |  |       | | |                |       |  |
    |  +-------+ | |                +-------+  |
    |      | ____| |                    | _____/
     \____/ /      | REPEAT       _____/ /       ELSE
           |       |             |      |
       +-------+   |             |  +-------+
       |       |   |             |  |       |
       +-------+   |             |  +-------+
           | ______/              \____ |
           |/        THEN              \|        THEN
           |                            |
    ---------------------------------------------------
    Figure A.3 - Extended control-flow pattern examples.
</pre>
<P>

Note that REPEAT creates an anomaly when matching the WHILE with ELSE or
THEN, most notable when compared with the BEGIN...UNTIL case.  That is,
there will be one less ELSE or THEN than there are WHILEs because REPEAT
resolves one THEN.  As above, if the user finds this count mismatch
undesirable, REPEAT could be replaced in-line by its own definition.

<P>

Other loop-exit control-flow words, and even other loops, can be
defined.  The only requirements are that the control-flow stack is
properly maintained and manipulated.

<P>

The simple implementation of the ANS Forth CASE structure below is an
example of control structure extension.  Note the maintenance of the
data stack to prevent interference with the possible control-flow stack
usage.

<P>


<PRE>
0 CONSTANT CASE IMMEDIATE  ( init count of OFs )

: OF  ( #of -- orig #of+1 / x -- )
    1+    ( count OFs )
    >R    ( move off the stack in case the control-flow )
          ( stack is the data stack. )
    POSTPONE OVER  POSTPONE = ( copy and test case value)
    POSTPONE IF    ( add orig to control flow stack )
    POSTPONE DROP  ( discards case value if = )
    R>             ( we can bring count back now )
; IMMEDIATE

: ENDOF ( orig1 #of -- orig2 #of )
    >R   ( move off the stack in case the control-flow )
         ( stack is the data stack. )
    POSTPONE ELSE
    R>   ( we can bring count back now )
; IMMEDIATE

: ENDCASE  ( orig1..orign #of -- )
    POSTPONE DROP  ( discard case value )
    0 ?DO
      POSTPONE THEN
    LOOP
; IMMEDIATE
</PRE>

<P>

<hr>
<a name=A.3.2.3.3>
<H4>A.3.2.3.3 Return stack</H4>
</a>

The restrictions in 
<a href=dpans3.htm#3.2.3.3>section 3.2.3.3</a> Return stack are necessary if
implementations are to be allowed to place loop parameters on the return
stack.

<P>


<hr>
<a name=A.3.2.6>
<H3>A.3.2.6 Environmental queries</H3>
</a>

The size in address units of various data types may be determined by
phrases such as <code><b>1 CHARS</code></b>.  
Similarly, alignment may be determined by
phrases such as <code><b>1 ALIGNED</code></b>.

<P>

The environmental queries are divided into two groups: those that always
produce the same value and those that might not.  The former groups
include entries such as MAX-N.  This information is fixed by the
hardware or by the design of the Forth system; a user is guaranteed that
asking the question once is sufficient.

<P>

The other group of queries are for things that may legitimately change
over time.  For example an application might test for the presence of
the Double Number word set using an environment query.  If it is
missing, the system could invoke a system-dependent process to load the
word set.  The system is permitted to change 
<a href=dpans6.htm#6.1.1345>ENVIRONMENT?</a>'s database so
that subsequent queries about it indicate that it is present.

<P>

Note that a query that returns an <B>unknown</B> response could produce
a <B>known</B> result on a subsequent query.

<P>


<hr>
<a name=A.3.3>
<H2>A.3.3 The Forth dictionary</H2>
</a>

A Standard Program may redefine a standard word with a non-standard
definition.  The program is still Standard (since it can be built on any
Standard System), but the effect is to make the combined entity
(Standard System plus Standard Program) a non-standard system.

<P>


<hr>
<a name=A.3.3.1>
<H3>A.3.3.1 Name space</H3>
</a>


<hr>
<a name=A.3.3.1.2>
<H4>A.3.3.1.2 Definition names</H4>
</a>

The language in this section is there to ensure the portability of
Standard Programs.  If a program uses something outside the Standard
that it does not provide itself, there is no guarantee that another
implementation will have what the program needs to run.  There is no
intent whatsoever to imply that all Forth programs will be somehow
lacking or inferior because they are not standard; some of the finest
jewels of the programmer's art will be non-standard.  At the same time,
the committee is trying to ensure that a program labeled <B>Standard</B>
will meet certain expectations, particularly with regard to portability.

<P>

In many system environments the input source is unable to supply certain
non-graphic characters due to external factors, such as the use of those
characters for flow control or editing.  In addition, when interpreting
from a text file, the parsing function specifically treats non-graphic
characters like spaces; thus words received by the text interpreter will
not contain embedded non-graphic characters.  To allow implementations
in such environments to call themselves Standard, this minor restriction
on Standard Programs is necessary.

<P>

A Standard System is allowed to permit the creation of definition names
containing non-graphic characters.  Historically, such names were used
for keyboard editing functions and <B>invisible</B> words.

<P>

<hr>
<a name=A.3.3.2>
<H3>A.3.3.2 Code space</H3>
</a>


<hr>
<a name=A.3.3.3>
<H3>A.3.3.3 Data space</H3>
</a>

The words 
<a href=dpans6.htm#6.2.0060>#TIB</a>, 
<a href=dpans6.htm#6.1.0560>&gt;IN</a>, 
<a href=dpans6.htm#6.1.0750>BASE</a>, 
<a href=dpans7.htm#7.6.1.0790>BLK</a>, 
<a href=dpans7.htm#7.6.2.2190>SCR</a>, 
<a href=dpans6.htm#6.1.2216>SOURCE</a>, 
<a href=dpans6.htm#6.2.2218>SOURCE-ID</a>, 
<a href=dpans6.htm#6.1.2250>STATE</a>, and 
<a href=dpans6.htm#6.2.2290>TIB</a>
contain information used by the Forth system in its operation and may be
of use to the application.  Any assumption made by the application about
data available in the Forth system it did not store other than the data
just listed is an environmental dependency.

<P>

There is no point in specifying (in the Standard) both what is and what
is not addressable.

<P>

A Standard Program may NOT address:
<P>

<UL>
<LI>Directly into the data or return stacks;
<LI>Into a definition's data field if not stored by the application.
</ul>
<P>

The read-only restrictions arise because some Forth systems run from ROM
and some share I/O buffers with other users or systems. Portable
programs cannot know which areas are affected, hence the general restrictions.


<P>

<hr>
<a name=A.3.3.3.1>
<H4>A.3.3.3.1 Address alignment</H4>
</a>

Many processors have restrictions on the addresses that can be used by
memory access instructions.  For example, on a Motorola 68000, 16-bit or
32-bit data can be accessed only at even addresses.  Other examples
include RISC architectures where 16-bit data can be loaded or stored
only at even addresses and 32-bit data only at addresses that are
multiples of four.

<P>

An implementor of ANS Forth can handle these alignment restrictions in
one of two ways.  Forth's memory access words 
(<a href=dpans6.htm#6.1.0650>@</a>, 
<a href=dpans6.htm#6.1.0010>!</a>, 
<a href=dpans6.htm#6.1.0130>+!</a>, 
etc.) could be
implemented in terms of smaller-width access instructions which have no
alignment restrictions.  For example, on a 68000 Forth with 16-bit
cells, @ could be implemented with two 68000 byte-fetch instructions and
a reassembly of the bytes into a 16-bit cell.  Although this conceals
hardware restrictions from the programmer, it is inefficient, and may
have unintended side effects in some hardware environments.  An
alternate implementation of ANS Forth could define each memory-access
word using the native instructions that most closely match the word's
function.  On a 68000 Forth with 16-bit cells, @ would use the 68000's
16-bit move instruction.  In this case, responsibility for giving @ a
correctly-aligned address falls on the programmer.  A portable ANS Forth
program must assume that alignment may be required and follow the
requirements of this section.

<P>

<hr>
<a name=A.3.3.3.2>
<H4>A.3.3.3.2 Contiguous regions</H4>
</a>

The data space of a Forth system comes in discontinuous regions! The
location of some regions is provided by the system, some by the program.
Data space is contiguous within regions, allowing address arithmetic to
generate valid addresses only within a single region.  A Standard
Program cannot make any assumptions about the relative placement of
multiple regions in memory.

<P>

<a href=dpans3.htm#3.3.3.2>Section 3.3.3.2</a>
does prescribe conditions under which contiguous regions
of data space may be obtained.  For example:

<PRE>
	CREATE TABLE   1 C, 2 C, ALIGN 1000 , 2000 ,
</PRE>
<P>

makes a table whose address is returned by TABLE.  In accessing this table,


<PRE>
TABLE C@                        will return 1
TABLE CHAR+ C@                  will return 2
TABLE 2 CHARS + ALIGNED @       will return 1000
TABLE 2 CHARS + ALIGNED CELL+ @ will return 2000.
</PRE>

<P>

Similarly,

<PRE>
	CREATE DATA   1000 ALLOT
</PRE>
<P>

makes an array 1000 address units in size.  A more portable strategy would
define the array in application units, such as:

<P>


<PRE>
	500 CONSTANT NCELLS
	CREATE CELL-DATA  NCELLS CELLS ALLOT
</PRE>

<P>

This array can be indexed like this:

<PRE>
	: LOOK   NCELLS 0 DO  CELL-DATA I CELLS + ? LOOP ;
</PRE>

<P>


<hr>
<a name=A.3.3.3.6>
<H4>A.3.3.3.6 Other transient regions</H4>
</a>

In many existing Forth systems, these areas are at 
<a href=dpans6.htm#6.1.1650>HERE</a> 
or just beyond
it, hence the many restrictions.

<P>

(2*n)+2 is the size of a character string containing the unpunctuated
binary representation of the maximum double number with a leading minus
sign and a trailing space.

<P>

<b>Implementation note:</b> Since the minimum value of n is 16, the absolute
minimum size of the pictured numeric output string is 34 characters.
But if your implementation has a larger n, you must also increase the
size of the pictured numeric output string.

<P>

<hr>
<a name=A.3.4>
<H2>A.3.4 The Forth text interpreter</H2>
</a>


<hr>
<a name=A.3.4.3>
<H3>A.3.4.3 Semantics</H3>
</a>

The <B>initiation semantics</B> correspond to the code that is executed
upon entering a definition, analogous to the code executed by 
<a href=dpans6.htm#6.1.1380>EXIT</a> upon
leaving a definition.  The <B>run-time semantics</B> correspond to code
fragments, such as literals or branches, that are compiled inside colon
definitions by words with explicit compilation semantics.

<P>

In a Forth cross-compiler, the execution semantics may be specified to
occur in the host system only, the target system only, or in both
systems.  For example, it may be appropriate for words such as 
<a href=dpans6.htm#6.1.0890>CELLS</a> to
execute on the host system returning a value describing the target, for
colon definitions to execute only on the target, and for 
<a href=dpans6.htm#6.1.0950>CONSTANT</a> and
<a href=dpans6.htm#6.1.2410>VARIABLE</a> 
to have execution behaviors on both systems.  Details of
cross-compiler behavior are beyond the scope of this Standard.

<P>

<hr>
<a name=A.3.4.3.2>
<H4>A.3.4.3.2 Interpretation semantics</H4>
</a>

For a variety of reasons, this Standard does not define interpretation
semantics for every word.  Examples of these words are 
<a href=dpans6.htm#6.1.0580>&gt;R</a>, 
<a href=dpans6.htm#6.1.0190>."</a>, 
<a href=dpans6.htm#6.1.1240>DO</a>, and
<a href=dpans6.htm#6.1.1700>IF</a>.  
Nothing in this Standard precludes an implementation from providing
interpretation semantics for these words, such as interactive
control-flow words.  However, a Standard Program may not use them in
interpretation state.

<P>

<hr>
<a name=A.3.4.5>
<H3>A.3.4.5 Compilation</H3>
</a>

Compiler recursion at the definition level consumes excessive resources,
especially to support locals.  The Technical Committee does not believe
that the benefits justify the costs.  Nesting definitions is also not
common practice and won't work on many systems.

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa4.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa4.htm/    845512620   500   0     100644  771       `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa3.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa5.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.4>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.4 Documentation requirements</H2>


<hr>
<A name=A.4.1>
<H3>A.4.1 System documentation</H3>
</a>


<hr>
<A name=A.4.2>
<H3>A.4.2 Program documentation</H3>
</a>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa5.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa5.htm/    845512620   500   0     100644  3615      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa4.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa6.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.5>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>


<H1>A.5 Compliance and labeling</H1>


<hr>
<a name=A.5.1>
<H2>A.5.1 ANS Forth systems</H2>
</a>

<a href=dpans5.htm#5.1>Section 5.1</a> defines the criteria that 
a system must meet in order to
justify the label <B>ANS Forth System</B>.  Briefly, the minimum
requirement is that the system must <B>implement</B> the Core word set.
There are several ways in which this requirement may be met.  The most
obvious is that all Core words may be in a pre-compiled kernel.  This is
not the only way of satisfying the requirement, however.  For example,
some words may be provided in source blocks or files with instructions
explaining how to add them to the system if they are needed.  So long as
the words are provided in such a way that the user can obtain access to
them with a clear and straightforward procedure, they may be considered
to be present.

<P>

A Forth cross-compiler has many characteristics in common with an ANS
Forth System, in that both use similar compiling tools to process a
program.  However, in order to fully specify an ANS Forth cross compiler
it would be necessary to address complex issues dealing with compilation
and execution semantics in both host and target environments as well as
ROMability issues.  The level of effort to do this properly has proved
to be impractical at this time.  As a result, although it may be
possible for a Forth cross-compiler to correctly prepare an ANS Forth
program for execution in a target environment, it is inappropriate for a
cross-compiler to be labeled an ANS Forth System.

<P>

<hr>
<a name=A.5.2>
<H2>A.5.2 ANS Forth programs</H2>
</a>


<hr>
<a name=A.5.2.2>
<H3>A.5.2.2 Program labeling</H3>
</a>

Declaring an environmental dependency should not be considered
undesirable, merely an acknowledgment that the author has taken
advantage of some assumed architecture.  For example, most computers in
common use are based on two's complement binary arithmetic.  By
acknowledging an environmental dependency on this architecture, a
programmer becomes entitled to use the number -1 to represent all bits
set without significantly restricting the portability of the program.

<P>

Because all programs require space for data and instructions, and time
to execute those instructions, they depend on the presence of an
environment providing those resources.  It is impossible to predict how
little of some of these resources (e.g.  stack space) might be necessary
to perform some task, so this Standard does not do so.

<P>

On the other hand, as a program requires increasing levels of resources,
there will probably be sucessively fewer systems on which it will
execute sucessfully.  An algorithm requiring an array of 109 cells might
run on fewer computers than one requiring only 103.

<P>

Since there is also no way of knowing what minimum level of resources
will be implemented in a system useful for at least some tasks, any
program performing real work labeled simply an <B>ANS Forth Program</B>
is unlikely to be labeled correctly.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa6.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa6.htm/    851247420   500   0     100644  49354     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa5.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa7.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.6>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.6 Glossary</H2>

In this and following sections we present rationales for the handling of
specific words: why we included them, why we placed them in certain word
sets, or why we specified their names or meaning as we did.

<P>

Words in this section are organized by word set, retaining their index
numbers for easy cross-referencing to the glossary.

<P>

Historically, many Forth systems have been written in Forth.  Many of
the words in Forth originally had as their primary purpose support of
the Forth system itself.  For example, WORD and FIND are often used as
the principle instruments of the Forth text interpreter, and CREATE in
many systems is the primitive for building dictionary entries.  In
defining words such as these in a standard way, we have endeavored not
to do so in such a way as to preclude their use by implementors.  One of
the features of Forth that has endeared it to its users is that the same
tools that are used to implement the system are available to the
application programmer - a result of this approach is the compactness
and efficiency that characterizes most Forth implementations.

<P>

<hr>
<a name=A.6.1>
<H3>A.6.1 Core words</H3>
</a>



<hr>
<a name=A.6.1.0070>A.6.1.0070 '</A>
<P>
</a>

Typical use:   <code>... ' name .</code>
<P>

Many Forth systems use a state-smart tick.  Many do not.  ANS Forth follows
the usage of Forth-83.

<P>
<code>
See:
<a href=dpansa3.htm#A.3.4.3.2>A.3.4.3.2</a> Interpretation semantics,
<a href=dpansa6.htm#A.6.1.1550>A.6.1.1550 FIND</a>
</code>
<P>

<hr>
<a name=A.6.1.0080>A.6.1.0080 (</A>
<P>

Typical use:   <code>...  ( ccc) ...</code>
<P>

<hr>
<a name=A.6.1.0140>A.6.1.0140 +LOOP</A>
<P>

Typical use:  <code>: X ... limit first DO ... step +LOOP ;</code>
<P>

<hr>
<a name=A.6.1.0150>A.6.1.0150 ,</A>
<P>

The use of , (comma) for compiling execution tokens is not portable.
<P>
<code>
See: 
<a href=dpans6.htm#6.2.0945>6.2.0945 COMPILE,</a>
</code>
<P>

<hr>
<a name=A.6.1.0190>A.6.1.0190 ."</A>
<P>

Typical use:    <code>: X ... ." ccc"  ... ;</code>
<P>

An implementation may define interpretation semantics for ." if desired.
In one plausible implementation, interpreting ." would display the
delimited message.  In another plausible implementation, interpreting ."
would compile code to display the message later.  In still another
plausible implementation, interpreting ." would be treated as an
exception.  Given this variation a Standard Program may not use ." while
interpreting.  Similarly, a Standard Program may not compile POSTPONE ."
inside a new word, and then use that word while interpreting.

<P>

<hr>
<a name=A.6.1.0320>A.6.1.0320 2*</A>
<P>

Historically, 2* has been implemented on two's-complement machines as a
logical left-shift instruction.  Multiplication by two is an efficient
side-effect on these machines.  However, shifting implies a knowledge of
the significance and position of bits in a cell.  While the name implies
multiplication, most implementors have used a hardware left shift to
implement 2*.

<P>

<hr>
<a name=A.6.1.0330>A.6.1.0330 2/</A>
<P>

This word has the same common usage and misnaming implications as 2*.
It is often implemented on two's-complement machines with a hardware
right shift that propagates the sign bit.

<P>

<hr>
<a name=A.6.1.0350>A.6.1.0350 2@</A>
<P>

With 2@ the storage order is specified by the Standard.

<P>

<hr>
<a name=A.6.1.0450>A.6.1.0450 :</A>
<P>

Typical use:    <code>: name ... ;</code>

<P>

In Forth-83, this word was specified to alter the search order.  This
specification is explicitly removed in this Standard.  We believe that
in most cases this has no effect; however, systems that allow many
search orders found the Forth-83 behavior of colon very undesirable.

<P>

Note that colon does not itself invoke the compiler.  Colon sets
compilation state so that later words in the parse area are compiled.

<P>

<hr>
<a name=A.6.1.0460>A.6.1.0460 ;</A>
<P>


Typical use:    <code>: name ... ;</code>

<P>

One function performed by both ; and ;CODE is to allow the current
definition to be found in the dictionary.  If the current definition was
created by :NONAME the current definition has no definition name and
thus cannot be found in the dictionary.  If :NONAME is implemented the
Forth compiler must maintain enough information about the current
definition to allow ; and ;CODE to determine whether or not any action
must be taken to allow it to be found.

<P>

<hr>
<a name=A.6.1.0550>A.6.1.0550 &gt;BODY</A>
<P>

a-addr is the address that HERE would have returned had it been executed
immediately after the execution of the CREATE that defined xt.

<P>

<hr>
<a name=A.6.1.0680>A.6.1.0680 ABORT"</A>
<P>

Typical use:    <code>: X ... test ABORT" ccc" ... ;</code>

<P>

<hr>
<a name=A.6.1.0695>A.6.1.0695 ACCEPT</A>
<P>

Previous standards specified that collection of the input string
terminates when either a <B>return</B> is received or when +n1
characters have been received.  Terminating when +n1 characters have
been received is difficult, expensive, or impossible to implement in
some system environments.  Consequently, a number of existing
implementations do not comply with this requirement.  Since line-editing
and collection functions are often implemented by system components
beyond the control of the Forth implementation, this Standard imposes no
such requirement.  A Standard Program may only assume that it can
receive an input string with ACCEPT or 
<a href=dpans6.htm#6.2.1390>EXPECT</a>.  
The detailed sequence of
user actions necessary to prepare and transmit that line are beyond the
scope of this Standard.

<P>

Specification of a non-zero, positive integer count (+n1) for ACCEPT
allows some implementors to continue their practice of using a zero or
negative value as a flag to trigger special behavior.  Insofar as such
behavior is outside the Standard, Standard Programs cannot depend upon
it, but the Technical Committee doesn't wish to preclude it
unnecessarily.  Since actual values are almost always small integers, no
functionality is impaired by this restriction.

<P>

ACCEPT and EXPECT perform similar functions.  ACCEPT is recommended for
new programs, and future use of EXPECT is discouraged.

<P>

It is recommended that all non-graphic characters be reserved for
editing or control functions and not be stored in the input string.

<P>

Commonly, when the user is preparing an input string to be transmitted
to a program, the system allows the user to edit that string and correct
mistakes before transmitting the final version of the string.  The
editing function is supplied sometimes by the Forth system itself, and
sometimes by external system software or hardware.  Thus, control
characters and functions may not be available on all systems.  In the
usual case, the end of the editing process and final transmission of the
string is signified by the user pressing a <B>Return</B> or <B>Enter</B>
key.

<P>

As in previous standards, EXPECT returns the input string immediately
after the requested number of characters are entered, as well as when a
line terminator is received.  The <B>automatic termination after
specified count of characters have been entered</B> behavior is widely
considered undesirable because the user <B>loses control</B> of the
input editing process at a potentially unknown time (the user does not
necessarily know how many characters were requested from EXPECT).  Thus
EXPECT and SPAN have been made obsolescent and exist in the Standard
only as a concession to existing implementations.  If EXPECT exists in a
Standard System it must have the <B>automatic termination</B> behavior.

<P>

ACCEPT does not have the <B>automatic termination</B> behavior of
EXPECT.  However, because external system hardware and software may
perform the ACCEPT function, when a line terminator is received the
action of the cursor, and therefore the display, is
implementation-defined.  It is recommended that the cursor remain
immediately following the entered text after a line terminator is
received.

<P>

<hr>
<a name=A.6.1.0705>A.6.1.0705 ALIGN</A>
<P>

In this Standard we have attempted to provide transportability across
various CPU architectures.  One of the frequent causes of
transportability problems is the requirement of cell-aligned addresses
on some CPUs.  On these systems, ALIGN and ALIGNED may be required to
build and traverse data structures built with C,.  Implementors may
define these words as no-ops on systems for which they aren't
functional.

<P>

<hr>
<a name=A.6.1.0706>A.6.1.0706 ALIGNED</A>
<P>
<code>
See: 
<a href=dpansa6.htm#A.6.1.0705>A.6.1.0705 ALIGN</a>
</code>
<P>

<hr>
<a name=A.6.1.0760>A.6.1.0760 BEGIN</A>
<P>

Typical use:	
<pre>
        : X ... BEGIN ... test UNTIL ;
</pre>

or
<P>


<PRE>
	: X ... BEGIN ... test WHILE ... REPEAT ;
</PRE>
<P>

<hr>
<a name=A.6.1.0770>A.6.1.0770 BL</A>
<P>

Because space is used throughout Forth as the standard delimiter, this
word is the only way a program has to find and use the system value of
<B>space</B>.  The value of a space character can not be obtained with
CHAR, for instance.

<P>

<hr>
<a name=A.6.1.0880>A.6.1.0880 CELL+</A>
<P>

As with ALIGN and ALIGNED, the words CELL and CELL+ were added to aid in
transportability across systems with different cell sizes.  They are
intended to be used in manipulating indexes and addresses in integral
numbers of cell-widths.

<P>

Example:

<PRE>
2VARIABLE DATA

0 100 DATA 2!
DATA @ . 100

DATA CELL+ @ .  0
</PRE>

<P>

<hr>
<a name=A.6.1.0890>A.6.1.0890 CELLS</A>
<P>
<code>
See:
<a href=dpansa6.htm#A.6.1.0880>A.6.1.0880 CELL+</a>
</code>
<P>

Example:  <code>CREATE NUMBERS  100 CELLS ALLOT</code>
<P>

(Allots space in the array NUMBERS for 100 cells of data.)

<P>

<hr>
<a name=A.6.1.0895>A.6.1.0895 CHAR</A>
<P>

Typical use:    <code>... CHAR A CONSTANT "A" ...</code>

<P>

<hr>
<a name=A.6.1.0950>A.6.1.0950 CONSTANT</A>
<P>

Typical use:    <code>... DECIMAL 10 CONSTANT TEN ...</code>

<P>

<hr>
<a name=A.6.1.1000>A.6.1.1000 CREATE</A>
<P>

The data-field address of a word defined by CREATE is given by the
data-space pointer immediately following the execution of CREATE

<P>

Reservation of data field space is typically done with ALLOT.

<P>

Typical use:    <code>... CREATE SOMETHING ...</code>

<P>

<hr>
<a name=A.6.1.1240>A.6.1.1240 DO</A>
<P>

Typical use:
<P>


<PRE>
	: X ... limit first DO ... LOOP ;
</PRE>
<P>

or
<P>


<PRE>
	: X ... limit first DO ... step +LOOP ;
</PRE>
<P>

<hr>
<a name=A.6.1.1250>A.6.1.1250 DOES&gt;</A>
<P>

Typical use:    <code>: X ... DOES&gt; ... ;</code>

<P>

Following DOES&gt;, a Standard Program may not make any assumptions
regarding the ability to find either the name of the definition
containing the DOES&gt; or any previous definition whose name may be
concealed by it.  DOES&gt; effectively ends one definition and begins
another as far as local variables and control-flow structures are
concerned.  The compilation behavior makes it clear that the user is not
entitled to place DOES&gt; inside any control-flow structures.

<P>

<hr>
<a name=A.6.1.1310>A.6.1.1310 ELSE</A>
<P>

Typical use:    <code>: X ... test IF ... ELSE ... THEN ;</code>

<P>

<hr>
<a name=A.6.1.1345>A.6.1.1345 ENVIRONMENT?</A>
<P>

In a Standard System that contains only the Core word set, effective use
of ENVIRONMENT? requires either its use within a definition, or the use
of user-supplied auxiliary definitions.  The Core word set lacks both a
direct method for collecting a string in interpretation state
(
<a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> 
S" is in an optional word set) and also a means to test the
returned flag in interpretation state (e.g.  the optional
<a href=dpans15.htm#15.6.2.2532>15.6.2.2532</a> [IF]).

<P>

The combination of 
<a href=dpans6.htm#6.1.1345>6.1.1345</a> ENVIRONMENT?, 
<a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S", 
<a href=dpans15.htm#15.6.2.2532>15.6.2.2532</a> [IF], 
<a href=dpans15.htm#15.6.2.2531>15.6.2.2531</a> [ELSE], and 
<a href=dpans15.htm#15.6.2.2533>15.6.2.2533</a> [THEN] constitutes an
effective suite of words for conditional compilation that works in
interpretation state.

<P>

<hr>
<a name=A.6.1.1360>A.6.1.1360 EVALUATE</A>
<P>

The Technical Committee is aware that this function is commonly spelled
EVAL.  However, there exist implementations that could suffer by
defining the word as is done here.  We also find EVALUATE to be more
readable and explicit.  There was some sentiment for calling this
INTERPRET, but that too would have undesirable effects on existing code.
The longer spelling was not deemed significant since this is not a word
that should be used frequently in source code.

<P>

<hr>
<a name=A.6.1.1380>A.6.1.1380 EXIT</A>
<P>

Typical use:    <code>: X ... test IF ... EXIT THEN ... ;</code>

<P>

<hr>
<a name=A.6.1.1550>A.6.1.1550 FIND</A>
<P>

One of the more difficult issues which the Committee took on was the
problem of divorcing the specification of implementation mechanisms from
the specification of the Forth language.  Three basic implementation
approaches can be quickly enumerated:

<P>

1) Threaded code mechanisms.  These are the traditional approaches to
implementing Forth, but other techniques may be used.

<P>

2) Subroutine threading with <B>macro-expansion</B> (code copying).
Short routines, like the code for DUP, are copied into a definition
rather than compiling a JSR reference.

<P>

3) Native coding with optimization.  This may include stack optimization
(replacing such phrases as 
<code>SWAP ROT +</code> with one or two machine
instructions, for example), parallelization (the trend in the newer RISC
chips is to have several functional subunits which can execute in
parallel), and so on.

<P>

The initial requirement (inherited from Forth-83) that compilation
addresses be compiled into the dictionary disallowed type 2 and type 3
implementations.

<P>

Type 3 mechanisms and optimizations of type 2 implementations were
hampered by the explicit specification of immediacy or non-immediacy of
all standard words.  POSTPONE allowed de-specification of immediacy or
non-immediacy for all but a few Forth words whose behavior must be
STATE-independent.

<P>

One type 3 implementation, Charles Moore's cmForth, has both compiling
and interpreting versions of many Forth words.  At the present, this
appears to be a common approach for type 3 implementations.  The
Committee felt that this implementation approach must be allowed.
Consequently, it is possible that words without interpretation semantics
can be found only during compilation, and other words may exist in two
versions: a compiling version and an interpreting version.  Hence the
values returned by FIND may depend on STATE, and ' and ['] may be unable
to find words without interpretation semantics.

<P>

<hr>
<a name=A.6.1.1561>A.6.1.1561 FM/MOD</A>
<P>

By introducing the requirement for <B>floored</B> division, Forth-83
produced much controversy and concern on the part of those who preferred
the more common practice followed in other languages of implementing
division according to the behavior of the host CPU, which is most often
symmetric (rounded toward zero).  In attempting to find a compromise
position, this Standard provides primitives for both common varieties,
floored and symmetric 
(<a href=dpans6.htm#6.1.2214>see</a> SM/REM).  FM/MOD is the floored version.

<P>

The Technical Committee considered providing two complete sets of
explicitly named division operators, and declined to do so on the
grounds that this would unduly enlarge and complicate the Standard.
Instead, implementors may define the normal division words in terms of
either FM/MOD or SM/REM providing they document their choice.  People
wishing to have explicitly named sets of operators are encouraged to do
so.  FM/MOD may be used, for example, to define:

<P>


<PRE>
: /_MOD ( n1 n2 -- n3 n4) >R S>D R> FM/MOD ;

: /_  ( n1 n2 -- n3)  /_MOD SWAP DROP ;

: _MOD ( n1 n2 -- n3)   /_MOD DROP ;

: */_MOD ( n1 n2 n3 -- n4 n5)  >R M* R> FM/MOD ;

: */_  ( n1 n2 n3 -- n4 )   */_MOD SWAP DROP ;
</PRE>

<P>

<hr>
<a name=A.6.1.1700>A.6.1.1700 IF</A>
<P>

Typical use:
<P>


<PRE>
	: X ... test IF ... THEN ... ;
</PRE>
<P>

or
<P>


<PRE>
	: X ... test IF ... ELSE ... THEN ... ;
</PRE>
<P>

<hr>
<a name=A.6.1.1710>A.6.1.1710 IMMEDIATE</A>
<P>

Typical use:    <code>: X  ...  ;  IMMEDIATE</code>

<P>

<hr>
<a name=A.6.1.1720>A.6.1.1720 INVERT</A>
<P>

The word NOT was originally provided in Forth as a flag operator to make
control structures readable.  Under its intended usage the following two
definitions would produce identical results:

<P>


<PRE>
: ONE  ( flag -- )
    IF ." true" ELSE ." false" THEN ;

: TWO ( flag -- )
    NOT IF ." false" ELSE ." true" THEN ;
</PRE>

<P>

This was common usage prior to the Forth-83 Standard which redefined NOT
as a cell-wide one's-complement operation, functionally equivalent to
the phrase 
<code>-1 XOR</code>. At the same time, the data type manipulated by this
word was changed from a flag to a cell-wide collection of bits and the
standard value for true was changed from <B>1</B> (rightmost bit only
set) to <B>-1</B> (all bits set).  As these definitions of TRUE and NOT
were incompatible with their previous definitions, many Forth users
continue to rely on the old definitions.  Hence both versions are in
common use.

<P>

Therefore, usage of NOT cannot be standardized at this time.  The two
traditional meanings of NOT - that of negating the sense of a flag and
that of doing a one's complement operation - are made available by 0=
and INVERT, respectively.

<P>

<hr>
<a name=A.6.1.1730>A.6.1.1730 J</A>
<P>

J may only be used with a nested DO...LOOP, DO...+LOOP, ?DO...LOOP, or
?DO...+LOOP, for example, in the form:


<PRE>
	: X ... DO ... DO ... J ... LOOP ... +LOOP ... ;
</PRE>
<P>

<hr>
<a name=A.6.1.1760>A.6.1.1760 LEAVE</A>
<P>

Note that LEAVE immediately exits the loop.  No words following LEAVE
within the loop will be executed.  Typical use:


<PRE>
	: X ... DO ... IF ... LEAVE THEN ... LOOP ... ;
</PRE>
<P>

<hr>
<a name=A.6.1.1780>A.6.1.1780 LITERAL</A>
<P>

Typical use:    <code>: X  ... [ x ] LITERAL ...  ;</code>

<P>

<hr>
<a name=A.6.1.1800>A.6.1.1800 LOOP</A>
<P>

Typical use:
<P>


<PRE>
	: X ... limit first DO ... LOOP ... ;
</PRE>
<P>

or
<P>


<PRE>
	: X ... limit first ?DO ... LOOP ... ;
</PRE>
<P>

<hr>
<a name=A.6.1.1810>A.6.1.1810 M*</A>
<P>

This word is a useful early step in calculation, going to extra
precision conveniently.  It has been in use since the Forth systems of
the early 1970's.

<P>

<hr>
<a name=A.6.1.1900>A.6.1.1900 MOVE</A>
<P>

CMOVE and CMOVE&gt; are the primary move operators in Forth-83.  They
specify a behavior for moving that implies propagation if the move is
suitably invoked.  In some hardware, this specific behavior cannot be
achieved using the best move instruction.  Further, CMOVE and CMOVE&gt;
move characters; ANS Forth needs a move instruction capable of dealing
with address units.  Thus MOVE has been defined and added to the Core
word set, and CMOVE and CMOVE&gt; have been moved to the String word set.

<P>

<hr>
<a name=A.6.1.2033>A.6.1.2033 POSTPONE</A>
<P>

Typical use:

<P>


<PRE>
: ENDIF  POSTPONE THEN ;  IMMEDIATE

: X  ... IF ... ENDIF ... ;
</PRE>

<P>

POSTPONE replaces most of the functionality of 
COMPILE and 
<a href=dpans6.htm#6.2.2530>[COMPILE]</a>.
COMPILE and [COMPILE] are used for the same purpose: postpone the
compilation behavior of the next word in the parse area.  COMPILE was
designed to be applied to non-immediate words and [COMPILE] to immediate
words.  This burdens the programmer with needing to know which words in
a system are immediate.  Consequently, Forth standards have had to
specify the immediacy or non-immediacy of all words covered by the
Standard.  This unnecessarily constrains implementors.

<P>

A second problem with COMPILE is that some programmers have come to
expect and exploit a particular implementation, namely:


<PRE>
	:  COMPILE  R>  DUP  @  ,  CELL+  >R  ;
</PRE>

<P>

This implementation will not work on native code Forth systems.  In a
native code Forth using inline code expansion and peephole optimization,
the size of the object code produced varies; this information is
difficult to communicate to a <B>dumb</B> COMPILE.  A <B>smart</B>
(i.e., immediate) COMPILE would not have this problem, but this was
forbidden in previous standards.

<P>

For these reasons, COMPILE has not been included in the Standard and
[COMPILE] has been moved in favor of POSTPONE.  Additional discussion
can be found in Hayes, J.R., <B>Postpone</B>, Proceedings of the 1989
Rochester Forth Conference.

<P>

<hr>
<a name=A.6.1.2120>A.6.1.2120 RECURSE</A>
<P>

Typical use:  <code>: X ... RECURSE ... ;</code>

<P>

This is Forth's recursion operator; in some implementations it is called
MYSELF.  The usual example is the coding of the factorial function.

<PRE>
: FACTORIAL ( +n1 -- +n2)
    DUP 2 &lt; IF  DROP 1 EXIT  THEN
    DUP 1-  RECURSE *
;
</PRE>

<P>

n2 = n1(n1-1)(n1-2)...(2)(1), the product of n1 with all positive
integers less than itself (as a special case, zero factorial equals
one).  While beloved of computer scientists, recursion makes unusually
heavy use of both stacks and should therefore be used with caution.  See
alternate definition in
<a href=dpansa6.htm#A.6.1.2140>A.6.1.2140</a> REPEAT.

<P>

<hr>
<a name=A.6.1.2140>A.6.1.2140 REPEAT</A>
<P>

Typical use:
<P>



<PRE>
: FACTORIAL ( +n1 -- +n2)
    DUP 2 < IF  DROP 1 EXIT  THEN
    DUP
    BEGIN DUP 2 > WHILE
        1-  SWAP OVER *  SWAP
    REPEAT  DROP
;
</PRE>

<P>

<hr>
<a name=A.6.1.2165>A.6.1.2165 S"</A>
<P>

Typical use:    <code>: X  ... S" ccc" ... ;</code>

<P>

This word is found in many systems under the name " (quote).  However,
current practice is almost evenly divided on the use of ", with many
systems using the execution semantics given here, while others return
the address of a counted string.  We attempt here to satisfy both camps
by providing two words, S" and the Core Extension word C" so that users
may have whichever behavior they expect with a simple renaming
operation.

<P>

<hr>
<a name=A.6.1.2214>A.6.1.2214 SM/REM</A>
<P>

See the previous discussion of division under FM/MOD.  SM/REM is the
symmetric-division primitive, which allows programs to define the
following symmetric-division operators:

<P>


<PRE>
: /-REM  ( n1 n2 -- n3 n4 )  >R  S>D  R> SM/REM ;

: /-  (  n1 n2 -- n3 )  /-REM SWAP DROP ;

: -REM  ( n1 n2 -- n3 )  /-REM DROP ;

: */-REM  (  n1 n2 n3 -- n4 n5 )  >R  M*  R> SM/REM ;

: */-  ( n1 n2 n3 -- n4 )  */-REM SWAP DROP ;
</PRE>

<P>

<hr>
<a name=A.6.1.2216>A.6.1.2216 SOURCE</A>
<P>

SOURCE simplifies the process of directly accessing the input buffer by
hiding the differences between its location for different input sources.
This also gives implementors more flexibility in their implementation of
buffering mechanisms for different input sources.  The committee moved
away from an input buffer specification consisting of a collection of
individual variables, declaring TIB and #TIB obsolescent.

<P>

SOURCE in this form exists in F83, POLYFORTH, LMI's Forths and others.
In conventional systems it is equivalent to the phrase


<PRE>
	BLK @  IF BLK @ BLOCK 1024  ELSE TIB #TIB @ THEN
</PRE>

<P>

<hr>
<a name=A.6.1.2250>A.6.1.2250 STATE</A>
<P>

Although EVALUATE, LOAD, INCLUDE-FILE, and INCLUDED are not listed as
words which alter STATE, the text interpreted by any one of these words
could include one or more words which explicitly alter STATE.  EVALUATE,
LOAD, INCLUDE-FILE, and INCLUDED do not in themselves alter STATE.

<P>

STATE does not nest with text interpreter nesting.  For example, the
code sequence:


<PRE>
	: FOO  S" ]" EVALUATE ;       FOO
</PRE>

<P>

will leave the system in compilation state.  Similarly, after LOADing a
block containing ], the system will be in compilation state.

<P>

Note that ] does not affect the parse area and that the only effect that
: has on the parse area is to parse a word.  This entitles a program to
use these words to set the state with known side-effects on the parse
area.  For example:

<P>


<PRE>
: NOP  : POSTPONE ; IMMEDIATE ;

NOP ALIGN    NOP ALIGNED
</PRE>

<P>

Some non-ANS Forth compliant systems have ] invoke a compiler loop in
addition to setting STATE.  Such a system would inappropriately attempt
to compile the second use of NOP.

<P>

Also note that nothing in the Standard prevents a program from finding
the execution tokens of ] or [ and using these to affect STATE.  These
facts suggest that implementations of ] will do nothing but set STATE
and a single interpreter/compiler loop will monitor STATE.


<P>

<hr>
<a name=A.6.1.2270>A.6.1.2270 THEN</A>
<P>

Typical use:
<P>


<PRE>
	: X ... test IF ... THEN ... ;
</PRE>
<P>

or
<P>


<PRE>
	: X ... test IF ... ELSE ... THEN ... ;
</PRE>
<P>

<hr>
<a name=A.6.1.2380>A.6.1.2380 UNLOOP</A>
<P>


Typical use:

<PRE>
: X  ...

   limit first DO

       ... test IF ... UNLOOP EXIT THEN ...

   LOOP
   ...
;
</PRE>

<P>

UNLOOP allows the use of EXIT within the context of DO ...  LOOP and
related do-loop constructs.  UNLOOP as a function has been called UNDO.
UNLOOP is more indicative of the action: nothing gets undone -- we
simply stop doing it.

<P>

<hr>
<a name=A.6.1.2390>A.6.1.2390 UNTIL</A>
<P>

Typical use:    <code>: X ... BEGIN ... test UNTIL ... ;</code>

<P>

<hr>
<a name=A.6.1.2410>A.6.1.2410 VARIABLE</A>
<P>


Typical use:    <code>... VARIABLE XYZ ...</code>

<P>

<hr>
<a name=A.6.1.2430>A.6.1.2430 WHILE</A>
<P>


Typical use:    <code>: X ... BEGIN ... test WHILE ... REPEAT ... ;</code>

<P>

<hr>
<a name=A.6.1.2450>A.6.1.2450 WORD</A>
<P>

Typical use:    <code>char WORD ccc&lt;char&gt;</code>

<P>

<hr>
<a name=A.6.1.2500>A.6.1.2500 [</A>
<P>

Typical use:    <code>: X ... [ 4321 ] LITERAL ... ;</code>

<P>

<hr>
<a name=A.6.1.2510>A.6.1.2510 [']</A>
<P>

Typical use:    <code>: X  ... ['] name ... ;</code>

<P>
<code>
See:  
<a href=dpansa6.htm#A.6.1.1550>A.6.1.1550 FIND</a>
</code>
<P>

<hr>
<a name=A.6.1.2520>A.6.1.2520 [CHAR]</A>
<P>

Typical use:    <code>: X  ...  [CHAR] ccc  ...  ;</code>

<P>

<hr>
<a name=A.6.1.2540>A.6.1.2540 ]</A>
<P>

Typical use:    <code>: X ... [ 1234 ] LITERAL ... ;</code>

<P>

 
<hr>
<a name=A.6.2>
<H3>A.6.2 Core extension words</H3>
</a>

The words in this collection fall into several categories:
<P>

<UL>
<LI>Words that are in common use but are deemed less essential than Core
words (e.g., 
<a href=dpans6.htm#6.2.0260>0&lt;&gt;</a>);
<LI>Words that are in common use but can be trivially defined from Core
words (e.g., 
<a href=dpans6.htm#6.2.1485>FALSE</a>);
<LI>Words that are primarily useful in narrowly defined types of
applications or are in less frequent use (e.g., 
<a href=dpans6.htm#6.2.2008>PARSE</a>);
<LI>Words that are being deprecated in favor of new words introduced to
solve specific problems (e.g., 
<a href=dpans6.htm#6.2.0970>CONVERT</a>).
</UL>
<P>

Because of the varied justifications for inclusion of these words, the
Technical Committee does not encourage implementors to offer the
complete collection, but to select those words deemed most valuable to
their clientele.

<P>

<hr>
<a name=A.6.2.0060>A.6.2.0060 #TIB</A>
<P>

The function of #TIB has been superseded by 
<a href=dpans6.htm#6.1.2216>SOURCE</a>.

<P>

<hr>
<a name=A.6.2.0200>A.6.2.0200 .(</A>
<P>

Typical use:    <code>.( ccc)</code>

<P>

<hr>
<a name=A.6.2.0210>A.6.2.0210 .R</A>
<P>

In .R, <B>R</B> is short for RIGHT.

<P>

<hr>
<a name=A.6.2.0340>A.6.2.0340 2&gt;R</A>
<P>

Historically, 2&gt;R has been used to implement 
<a href=dpans6.htm#6.1.1240>DO</a>.  Hence the order of
parameters on the return stack.

<P>

The primary advantage of 2&gt;R is that it puts the top stack entry on the
top of the return stack.  For instance, a double-cell number may be
transferred to the return stack and still have the most significant cell
accessible on the top of the return stack.

<P>

<hr>
<a name=A.6.2.0410>A.6.2.0410 2R&gt;</A>
<P>

Note that 2R&gt; is not equivalent to 
<a href=dpans6.htm#6.1.2060>R&gt;</a> R&gt;.  Instead, it mirrors the
action of 
<a href=dpans6.htm#6.2.0340>2&gt;R</a> 
(see <a href=dpansa6.htm#A.6.2.0340>A.6.2.0340</A>).

<P>

<hr>
<a name=A.6.2.0455>A.6.2.0455 :NONAME</A>
<P>

:NONAME allows a user to create an execution token with the semantics of
a colon definition without an associated name.  Previously, only 
<a href=dpans6.htm#6.1.0450>:</a>
(colon) could create an execution token with these semantics.  Thus,
Forth code could only be compiled using the syntax of :, that is:


<PRE>
	: NAME  ...  ;
</PRE>

<P>

:NONAME removes this constraint and places the Forth compiler in the
hands of the programmer.

<P>

:NONAME can be used to create application-specific programming
languages.  One technique is to mix Forth code fragments with
application-specific constructs.  The application-specific constructs
use :NONAME to compile the Forth code and store the corresponding
execution tokens in data structures.

<P>

The functionality of :NONAME can be built on any Forth system.  For
years, expert Forth programmers have exploited intimate knowledge of
their systems to generate unnamed code fragments.  Now, this function
has been named and can be used in a portable program.

<P>

For example, :NONAME can be used to build a table of code fragments
where indexing into the table allows executing a particular fragment.
The declaration syntax of the table is:

<P>


<PRE>
:NONAME .. code for command 0 .. ;  0 CMD !

:NONAME .. code for command 1 .. ;  1 CMD !
   ...

:NONAME .. code for command 99 .. ; 99 CMD !

   ... 5 CMD @ EXECUTE ...

</PRE>
<P>

The definitions of the table building words are:

<PRE>
CREATE CMD-TABLE  \ table for command execution tokens
100 CELLS ALLOT

: CMD ( n -- a-addr ) \ nth element address in table
    CELLS CMD-TABLE + ;
</PRE>

<P>

As a further example, a defining word can be created to allow
performance monitoring.  In the example below, the number of times a
word is executed is counted.  : must first be renamed to allow the
definition of the new ;.

<P>


<PRE>
: DOCOLON ( -- )     \ Modify CREATEd word to execute like a colon def
     DOES> ( i*x a-addr -- j*x )
     1 OVER +!         \ count executions
     CELL+ @ EXECUTE   \ execute :NONAME definition
;

: OLD: : ;           \ just an alias

OLD: : ( "name" -- a-addr xt colon-sys )
                     \ begins an execution-counting colon definition
     CREATE  HERE 0 ,  \ storage for execution counter
     0 ,               \ storage for execution token
     DOCOLON           \ set run time for CREATEd word
    :NONAME           \ begin unnamed colon definition
;
</PRE>
<P>

( Note the placement of DOES&gt;: DOES&gt; must modify the CREATEd word and not
the :NONAME definition, so DOES&gt; must execute before :NONAME.)

<PRE>
OLD: ; ( a-addr xt colon-sys -- )
                      \ ends an execution-counting colon definition )
    POSTPONE ;        \ complete compilation of colon def
    SWAP CELL+ !      \ save execution token
;  IMMEDIATE
</PRE>

<P>

The new : and ; are used just like the standard ones to define words:
<P>


<PRE>
	... : xxx  ... ;  ...  xxx  ...
</PRE>

Now however, these words may be <B>ticked</B> to retrieve the count (and
execution token):


<PRE>
	... ' xxx >BODY ? ...
</PRE>

<P>

<hr>
<a name=A.6.2.0620>A.6.2.0620 ?DO</A>
<P>

Typical use:

<code>: FACTORIAL ( +n1 -- +n2 )  1 SWAP 1+ ?DO  I *  LOOP ;</code>

<P>

This word was added in response to many requests for a resolution of the
difficulty introduced by Forth-83's DO, which on a 16-bit system will
loop 65,535 times if given equal arguments.  As this Standard also
encourages 32-bit systems, this behavior can be intolerable.  The
Technical Committee considered applying these semantics to 
<a href=dpans6.htm#6.1.1240>DO</a>, but
declined on the grounds that it might break existing code.

<P>

<hr>
<a name=A.6.2.0700>A.6.2.0700 AGAIN</A>
<P>

Typical use:    <code>: X ... BEGIN ... AGAIN ... ;</code>

<P>

Unless word-sequence has a way to terminate, this is an endless loop.

<P>

<hr>
<a name=A.6.2.0855>A.6.2.0855 C"</A>
<P>

Typical use:    <code>: X  ...  C" ccc"  ...  ;</code>

<P>

It is easy to convert counted strings to pointer/length but hard to do
the opposite.  C" is the only new word that uses the <B>address of
counted string</B> stack representation.  It is provided as an aid to
porting existing programs to ANS Forth systems.  It is relatively
difficult to implement C" in terms of other standard words, considering
its <B>compile string into the current definition</B> semantics.

<P>

Users of C" are encouraged to migrate their application code toward the
consistent use of the preferred <B>c-addr u</B> stack representation
with the alternate word 
<a href=dpans6.htm#6.1.2165>S"</a>.  This may be accomplished by converting
application words with counted string input arguments to use the
preferred <B>c-addr u</B> representation, thus eliminating the need for
C" .

<P>
<code>
See:
<a href=dpansa3.htm#A.3.1.3.4>A.3.1.3.4</a> Counted strings
</code>
<P>

<hr>
<a name=A.6.2.0873>A.6.2.0873 CASE</A>
<P>

Typical use:

<PRE>
   : X ...
       CASE
       test1 OF ... ENDOF
       testn OF ... ENDOF
       ... ( default )
       ENDCASE ...
   ;
</PRE>

<P>

<hr>
<a name=A.6.2.0945>A.6.2.0945 COMPILE,</A>
<P>

COMPILE, is the compilation equivalent of 
<a href=dpans6.htm#6.1.1370>EXECUTE</a>.  In many cases, it is
possible to compile a word by using 
<a href=dpans6.htm#6.1.2033>POSTPONE</a> without resorting to the
use of COMPILE,.  However, the use of POSTPONE requires that the name of
the word must be known at compile time, whereas COMPILE, allows the word
to be located at any time.  It is sometime possible to use 
<a href=dpans6.htm#6.1.1360>EVALUATE</a> to
compile a word whose name is not known until run time.  This has two
possible problems:

<UL>
<LI>EVALUATE is slower than COMPILE, because a dictionary search is
required.
<LI>The current search order affects the outcome of EVALUATE.
</UL>
<P>

In traditional threaded-code implementations, compilation is performed
by 
<a href=dpans6.htm#6.1.0150>,</a> (comma).  
This usage is not portable; it doesn't work for
subroutine-threaded, native code, or relocatable implementations.  Use
of COMPILE, is portable.

<P>

In most systems it is possible to implement COMPILE, so it will generate
code that is optimized to the same extent as code that is generated by
the normal compilation process.  However, in some implementations there
are two different <B>tokens</B> corresponding to a particular definition
name: the normal <B>execution token</B> that is used while interpreting
or with EXECUTE, and another <B>compilation token</B> that is used while
compiling.  It is not always possible to obtain the compilation token
from the execution token.  In these implementations, COMPILE, might not
generate code that is as efficient as normally compiled code.

<P>

<hr>
<a name=A.6.2.0970>A.6.2.0970 CONVERT</A>
<P>

CONVERT may be defined as follows:


<PRE>
	: CONVERT   CHAR+ 65535 >NUMBER DROP ;
</PRE>

<P>

<hr>
<a name=A.6.2.1342>A.6.2.1342 ENDCASE</A>
<P>

Typical use:

<PRE>
   : X ...
       CASE
       test1 OF ... ENDOF
       testn OF ... ENDOF
       ... ( default )
       ENDCASE ...
   ;
</PRE>

<P>

<hr>
<a name=A.6.2.1343>A.6.2.1343 ENDOF</A>
<P>

Typical use:

<PRE>
: X ...
   CASE
   test1 OF ... ENDOF
   testn OF ... ENDOF
   ... ( default )
   ENDCASE ...
;
</PRE>

<P>

<hr>
<a name=A.6.2.1390>A.6.2.1390 EXPECT</A>
<P>

Specification of positive integer counts (+n) for EXPECT allows some
implementors to continue their practice of using a zero or negative
value as a flag to trigger special behavior.  Insofar as such behavior
is outside the Standard, Standard Programs cannot depend upon it, but
the Technical Committee doesn't wish to preclude it unnecessarily.
Since actual values are almost always small integers, no functionality
is impaired by this restriction.

<P>

<hr>
<a name=A.6.2.1850>A.6.2.1850 MARKER</A>
<P>

As dictionary implementations have gotten more elaborate and in some
cases have used multiple address spaces, 
<a href=dpans15.htm#15.6.2.1580>FORGET</a> has become prohibitively
difficult or impossible to implement on many Forth systems.  MARKER
greatly eases the problem by making it possible for the system to
remember <B>landmark information</B> in advance that specifically marks
the spots where the dictionary may at some future time have to be
rearranged.

<P>

<hr>
<a name=A.6.2.1950>A.6.2.1950 OF</a>
<P>

Typical use:

<PRE>
   : X ...
       CASE
       test1 OF ... ENDOF
       testn OF ... ENDOF
       ... ( default )
       ENDCASE ...
   ;
</PRE>

<P>

<hr>
<a name=A.6.2.2000>A.6.2.2000 PAD</A>
<P>

PAD has been available as scratch storage for strings since the earliest
Forth implementations.  It was brought to our attention that many
programmers are reluctant to use PAD, fearing incompatibilities with
system uses.  PAD is specifically intended as a programmer convenience,
however, which is why we documented the fact that no standard words use
it.

<P>

<hr>
<a name=A.6.2.2008>A.6.2.2008 PARSE</A>
<P>

Typical use:    <code>char PARSE ccc&lt;char&gt;</code>

<P>

The traditional Forth word for parsing is 
<a href=dpans6.htm#6.1.2450>WORD</a>.  PARSE solves the
following problems with WORD:

<P>

a) WORD always skips leading delimiters.  This behavior is appropriate
for use by the text interpreter, which looks for sequences of non-blank
characters, but is inappropriate for use by words like ( , .( , and ." .
Consider the following (flawed) definition of .( :


<PRE>
	: .(   [CHAR] )  WORD COUNT TYPE ;  IMMEDIATE
</PRE>

<P>

This works fine when used in a line like:


<PRE>
	.( HELLO)   5 .
</PRE>

<P>

but consider what happens if the user enters an empty string:


<PRE>
	.( )   5 .
</PRE>

<P>

The definition of .( shown above would treat the ) as a leading
delimiter, skip it, and continue consuming characters until it located
another ) that followed a non-) character, or until the parse area was
empty.  In the example shown, the 5 .  would be treated as part of the
string to be printed.

<P>

With PARSE, we could write a correct definition of .( :


<PRE>
	: .(   [CHAR] ) PARSE TYPE ; IMMEDIATE
</PRE>

<P>

This definition avoids the <B>empty string</B> anomaly.

<P>

b)      WORD returns its result as a counted string.  This has four bad
effects:

<P>

1)      The characters accepted by WORD must be copied from the input buffer
into a temporary buffer, in order to make room for the count character that
must be at the beginning of the counted string.  The copy step is inefficient,
compared to PARSE, which leaves the string in the input buffer and doesn't
need to copy it anywhere.

<P>

2)      WORD must be careful not to store too many characters into the
temporary buffer, thus overwriting something beyond the end of the buffer.
This adds to the overhead of the copy step.  (WORD may have to scan a lot of
characters before finding the trailing delimiter.)

<P>

3)      The count character limits the length of the string returned by WORD
to 255 characters (longer strings can easily be stored in blocks!).  This
limitation does not exist for PARSE.

<P>

4)      The temporary buffer is typically overwritten by the next use of WORD.
This introduces a temporal dependency; the value returned by WORD is only
valid for a limited duration.  PARSE has a temporal dependency, too, related
to the lifetime of the input buffer, but that is less severe in most cases
than WORD's temporal dependency.

<P>

The behavior of WORD with respect to skipping leading delimiters is
useful for parsing blank-delimited names.  Many system implementations
include an additional word for this purpose, similar to PARSE with
respect to the <B>c-addr u</B> return value, but without an explicit
delimiter argument (the delimiter set is implicitly <B>white space</B>),
and which does skip leading delimiters.  A common description for this
word is:


<PRE>
	PARSE-WORD  ( &lt;spaces&gt;name -- c-addr u )
</PRE>

<P>

Skip leading spaces and parse name delimited by a space.  c-addr is the
address within the input buffer and u is the length of the selected string.
If the parse area is empty, the resulting string has a zero length.

<P>

If both PARSE and PARSE-WORD are present, the need for WORD is largely
eliminated.

<P>

<hr>
<a name=A.6.2.2030>A.6.2.2030 PICK</A>
<P>

0 PICK is equivalent to 
<a href=dpans6.htm#6.1.1290>DUP</a> and 1 PICK is equivalent to 
<a href=dpans6.htm#6.1.1990>OVER</a>.

<P>

<hr>
<a name=A.6.2.2040>A.6.2.2040 QUERY</A>
<P>

The function of QUERY may be performed with 
<a href=dpans6.htm#6.1.0695>ACCEPT</a> and 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>.

<P>

<hr>
<a name=A.6.2.2125>A.6.2.2125 REFILL</A>
<P>

This word is a useful generalization of 
<a href=dpans6.htm#6.2.2040>QUERY</a>.  Re-defining QUERY to
meet this specification would have broken existing code.  REFILL is
designed to behave reasonably for all possible input sources.  If the
input source is coming from the user, as with QUERY, REFILL could still
return a false value if, for instance, a communication channel closes so
that the system knows that no more input will be available.

<P>

<hr>
<a name=A.6.2.2150>A.6.2.2150 ROLL</A>
<P>

2 ROLL is equivalent to 
<a href=dpans6.htm#6.1.2160>ROT</a>, 
1 ROLL is equivalent to 
<a href=dpans6.htm#6.1.2260>SWAP</a> and 0 ROLL is
a null operation.

<P>

<hr>
<a name=A.6.2.2182>A.6.2.2182 SAVE-INPUT</A>
<P>

SAVE-INPUT and 
<a href=dpans6.htm#6.2.2148>RESTORE-INPUT</a> 
allow the same degree of input source
repositioning within a text file as is available with 
<a href=dpans7.htm#7.6.1.0800>BLOCK</a> input.
SAVE-INPUT and RESTORE-INPUT <B>hide the details</B> of the operations
necessary to accomplish this repositioning, and are used the same way
with all input sources.  This makes it easier for programs to reposition
the input source, because they do not have to inspect several variables
and take different action depending on the values of those variables.

<P>

SAVE-INPUT and RESTORE-INPUT are intended for repositioning within a
single input source; for example, the following scenario is NOT allowed
for a Standard Program:

<PRE>
   : XX
       SAVE-INPUT  CREATE
       S" RESTORE-INPUT" EVALUATE
       ABORT" couldn't restore input"
   ;
</PRE>

<P>

This is incorrect because, at the time RESTORE-INPUT is executed, the
input source is the string via 
<a href=dpans6.htm#6.1.1360>EVALUATE</a>, which is not the same input
source that was in effect when SAVE-INPUT was executed.

<P>

The following code is allowed:


<PRE>
: XX
    SAVE-INPUT  CREATE
    S" .( Hello)" EVALUATE
    RESTORE-INPUT ABORT" couldn't restore input"
;
</PRE>
 
<P>

After EVALUATE returns, the input source specification is restored to
its previous state, thus SAVE-INPUT and RESTORE-INPUT are called with
the same input source in effect.

<P>

In the above examples, the EVALUATE phrase could have been replaced by a
phrase involving 
<a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a> 
and the same rules would apply.

<P>

The Standard does not specify what happens if a program violates the
above rules.  A Standard System might check for the violation and return
an exception indication from RESTORE-INPUT, or it might fail in an
unpredictable way.

<P>

The return value from RESTORE-INPUT is primarily intended to report the
case where the program attempts to restore the position of an input
source whose position cannot be restored.  The keyboard might be such an
input source.

<P>

Nesting of SAVE-INPUT and RESTORE-INPUT is allowed.  For example, the
following situation works as expected:

<PRE>
: XX
    SAVE-INPUT
    S" f1" INCLUDED      \ The file "f1" includes:
    \   ... SAVE-INPUT ... RESTORE-INPUT ...
    \ End of file "f1"
    RESTORE-INPUT  ABORT" couldn't restore input"
;
</PRE>

<P>

In principle, RESTORE-INPUT could be implemented to <B>always fail</B>, e.g.:

<PRE>
: RESTORE-INPUT  ( x1 ... xn n -- flag )
    0 ?DO DROP LOOP TRUE
;
</PRE>

<P>

Such an implementation would not be useful in most cases.  It would be
preferable for a system to leave SAVE-INPUT and RESTORE-INPUT undefined,
rather than to create a useless implementation.  In the absence of the
words, the application programmer could choose whether or not to create
<B>dummy</B> implementations or to work-around the problem in some other
way.

<P>

Examples of how an implementation might use the return values from
SAVE-INPUT to accomplish the save/restore function:

<P>


<PRE>
Input Source    possible stack values
------------    ---------------------
block           &gt;IN @  BLK @  2
EVALUATE        &gt;IN @  1
keyboard        &gt;IN @  1
text file       &gt;IN @  lo-pos  hi-pos  3
</PRE>

<P>

These are examples only; a Standard Program may not assume any particular
meaning for the individual stack items returned by SAVE-INPUT.

<P>

<hr>
<a name=A.6.2.2290>A.6.2.2290 TIB</A>
<P>

The function of TIB has been superseded by 
<a href=dpans6.htm#6.1.2216>SOURCE</a>.

<P>

<hr>
<a name=A.6.2.2295>A.6.2.2295 TO</A>
<P>

Historically, some implementations of TO have not explicitly parsed.
Instead, they set a mode flag that is tested by the subsequent execution
of name.  ANS Forth explicitly requires that TO must parse, so that TO's
effect will be predictable when it is used at the end of the parse area.

<P>

Typical use:    <code>x TO name</code>

<P>

<hr>
<a name=A.6.2.2298>A.6.2.2298 TRUE</A>
<P>

TRUE is equivalent to the phrase  <code>0 0=</code>.

<P>

<hr>
<a name=A.6.2.2405>A.6.2.2405 VALUE</A>
<P>

Typical use:

<PRE>
0 VALUE DATA

: EXCHANGE ( n1 -- n2 ) DATA SWAP TO DATA ;
</PRE>

<P>

EXCHANGE leaves n1 in DATA and returns the prior value n2.

<P>

<hr>
<a name=A.6.2.2440>A.6.2.2440 WITHIN</A>
<P>

We describe WITHIN without mentioning circular number spaces (an
undefined term) or providing the code.  Here is a number line with the
overflow point (o) at the far right and the underflow point (u) at the
far left:

<PRE>
u--------------------------------------------------------------o
</PRE>

<P>

There are two cases to consider: either the n2|u2..n3|u3 range straddles
the overflow/underflow points or it does not.  Lets examine the
non-straddle case first:

<PRE>
u-------------------[.....................)------------------------o
</PRE>

<P>

The [ denotes n2|u2, the ) denotes n3|u3, and the dots and [ are numbers
WITHIN the range.  n3|u3 is greater than n2|u2, so the following tests
will determine if n1|u1 is WITHIN n2|u2 and n3|u3:

<p>
<pre>
           n2|u2 &lt; n1|u1  and  n1|u1 &lt; n3|u3.
</pre>
<P>

In the case where the comparison range straddles the overflow/underflow
points:
<P>

u...............)-----------------------------[........................o

<p>

n3|u3 is less than n2|u2 and the following tests will determine if n1|u1 is
WITHIN n2|u2 and n3|u3:

<P>
<pre>
           n2|u2 &gt; n1|u1  and  n1|u1 &gt; n3|u3.
</pre>
<P>


WITHIN must work for both signed and unsigned arguments.  One obvious
implementation does not work:

<PRE>
: WITHIN  ( test low high -- flag )
    &gt;R  OVER &lt; 0= ( test flag1 )
    SWAP R&gt; &lt;     ( flag1 flag2 )
    AND
;
</PRE>

<P>

Assume two's-complement arithmetic on a 16-bit machine, and consider the
following test:


<PRE>
	33000  32000 34000  WITHIN
</PRE>

<P>

The above implementation returns false for that test, even though the
unsigned number 33000 is clearly within the range {{32000 ..  34000}}.

<P>

The problem is that, in the incorrect implementation, the signed
comparison 
&lt; gives the wrong answer when 32000 is compared to 33000,
because when those numbers are treated as signed numbers, 33000 is
treated as negative 32536, while 32000 remains positive.

<P>

Replacing &lt; with 
<a href=dpans6.htm#6.1.2340>U&lt;</a> 
in the above implementation makes it work with
unsigned numbers, but causes problems with certain signed number ranges;
in particular, the test:


<PRE>
	1  -5  5  WITHIN
</PRE>

<P>

would give an incorrect answer.

<P>

For two's-complement machines that ignore arithmetic overflow (most
machines), the following implementation works in all cases:

<PRE>
:  WITHIN  ( test low high -- flag )   OVER - &gt;R - R&gt;  U&lt;  ;

</PRE>
<P>

<hr>
<a name=A.6.2.2530>A.6.2.2530 [COMPILE]</A>
<P>

Typical use:    <code>: name2 ... [COMPILE] name1 ... ;  IMMEDIATE</code>

<P>

<hr>
<a name=A.6.2.2535>A.6.2.2535 \</A>
<P>

Typical use:    <code>5 CONSTANT THAT  \  THIS IS A COMMENT ABOUT THAT</code>

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa7.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa7.htm/    845512620   500   0     100644  2277      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa6.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa8.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.7>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>


<H2>A.7 The optional Block word set</H2>

Early Forth systems ran stand-alone, with no host OS.  Blocks of 1024
bytes were designed as a convenient unit of disk, and most native Forth
systems still use them.  It is relatively easy to write a native disk
driver that maps head/track/sector addresses to block numbers.  Such
disk drivers are extremely fast in comparison with conventional
file-oriented operating systems, and security is high because there is
no reliance on a disk map.

<P>

Today many Forth implementations run under host operating systems,
because the compatibility they offer the user outweighs the performance
overhead.  Many people who use such systems prefer using host OS files
only; however, people who use both native and non-native Forths need a
compatible way of accessing disk.  The Block Word set includes the most
common words for accessing program source and data on disk.

<P>

In order to guarantee that Standard Programs that need access to mass
storage have a mechanism appropriate for both native and non-native
implementations, ANS Forth requires that the Block word set be available
if any mass storage facilities are provided.  On non-native
implementations, blocks normally reside in host OS files.

<P>

<hr>
<a name=A.7.2>
<H3>A.7.2 Additional terms</H3>
</a>

<DL><DT><B>block</B>
<DD>Many Forth systems use blocks to contain program source.  Conventionally
such blocks are formatted for editing as 16 lines of 64 characters.
Source blocks are often referred to as <B>screens</B>.</DL>

<P>

<hr>
<a name=A.7.6>
<H3>A.7.6 Glossary</H3>
</a>


<hr>
<a name=A.7.6.2.2190>
A.7.6.2.2190   SCR
</a>
<P>

SCR is short for screen.

<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansa8.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansa8.htm/    850759200   500   0     100644  3484      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa7.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa9.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.8>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.8 The optional Double-Number word set</H2>

Forth systems on 8-bit and 16-bit processors often find it necessary to
deal with double-length numbers.  But many Forths on small embedded
systems do not, and many users of Forth on systems with a cell size of
32-bits or more find that the necessity for double-length numbers is
much diminished.  Therefore, we have factored the words that manipulate
double-length entities into this optional word set.

<P>

Please note that the naming convention used in this word set conveys
some important information:

<P>

1.  Words whose names are of the form 2xxx deal with cell pairs, where
the relationship between the cells is unspecified.  They may be
two-vectors, double-length numbers, or any pair of cells that it is
convenient to manipulate together.

<P>

2.  Words with names of the form Dxxx deal specifically with
double-length integers.

<P>

3.  Words with names of the form Mxxx deal with some combination of
single and double integers.  The order in which these appear on the
stack is determined by long-standing common practice.

<P>

Refer to 
<a href=dpansa3.htm#A.3.1>A.3.1</a> for a discussion of data types in Forth.

<P>

<hr>
<a name=A.8.6>
<H3>A.8.6 Glossary</H3>
</a>


<hr>
<a name=A.8.6.1.0360>A.8.6.1.0360 2CONSTANT</A>
<P>

Typical use:    <code>x1 x2 2CONSTANT name</code>

<P>

<hr>
<a name=A.8.6.1.0390>A.8.6.1.0390 2LITERAL</A>
<P>

Typical use:    <code>: X ... [ x1 x2 ] 2LITERAL ... ;</code>

<P>

<hr>
<a name=A.8.6.1.0440>A.8.6.1.0440 2VARIABLE</A>
<P>

Typical use:    <code>2VARIABLE name</code>

<P>

<hr>
<a name=A.8.6.1.1070>A.8.6.1.1070 D.R</A>
<P>

In D.R, the <B>R</B> is short for RIGHT.

<P>

<hr>
<a name=A.8.6.1.1090>A.8.6.1.1090 D2*</A>
<P>
<code>
See: 
<a href=dpansa6.htm#A.6.1.0320>A.6.1.0320 2*</a> for applicable
discussion.
</code>
<P>

<hr>
<a name=A.8.6.1.1100>A.8.6.1.1100 D2/</A>
<P>
<code>
See: 
<a href=dpansa6.htm#A.6.1.0330>A.6.1.0330 2/</a> for applicable
discussion.
</code>
<P>

<hr>
<a name=A.8.6.1.1140>A.8.6.1.1140 D&gt;S</A>
<P>

There exist number representations, e.g., the sign-magnitude
representation, where reduction from double- to single-precision cannot
simply be done with 
<a href=dpans6.htm#6.1.1260>DROP</a>.  
This word, equivalent to DROP on two's
complement systems, desensitizes application code to number
representation and facilitates portability.

<P>

<hr>
<a name=A.8.6.1.1820>A.8.6.1.1820 M*/</A>
<P>

M*/ was once described by Chuck Moore as the most useful arithmetic
operator in Forth.  It is the main workhorse in most computations
involving double-cell numbers.  Note that some systems allow signed
divisors.  This can cost a lot in performance on some CPUs.  The
requirement for a positive divisor has not proven to be a problem.

<P>

<hr>
<a name=A.8.6.1.1830>A.8.6.1.1830 M+</A>
<P>

M+ is the classical method for integrating.

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa9.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansa9.htm/    850759260   500   0     100644  8617      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa8.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansa10.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=A.9>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H2>A.9 The optional Exception word set</H2>

<a href=dpans9.htm#9.6.1.0875>CATCH</a> and 
<a href=dpans9.htm#9.6.1.2275>THROW</a> 
provide a reliable mechanism for handling exceptions,
without having to propagate exception flags through multiple levels of
word nesting.  It is similar in spirit to the <B>non-local return</B>
mechanisms of many other languages, such as C's setjmp() and longjmp(),
and LISP's CATCH and THROW.  In the Forth context, THROW may be
described as a <B>multi-level</b> 
<a href=dpans6.htm#6.1.1380>EXIT</a>, 
with CATCH marking a location to
which a THROW may return.

<P>

Several similar Forth <B>multi-level EXIT</B> exception-handling schemes
have been described and used in past years.  It is not possible to
implement such a scheme using only standard words (other than CATCH and
THROW), because there is no portable way to <B>unwind</B> the return
stack to a predetermined place.

<P>

THROW also provides a convenient implementation technique for the
standard words 
<a href=dpans6.htm#6.1.0670>ABORT</a> and 
<a href=dpans6.htm#6.1.0680>ABORT"</a>, 
allowing an application to define,
through the use of CATCH, the behavior in the event of a system ABORT.

<P>

This sample implementation of CATCH and THROW uses the non-standard
words described below.  They or their equivalents are available in many
systems.  Other implementation strategies, including directly saving the
value of 
<a href=dpans6.htm#6.1.1200>DEPTH</a>, 
are possible if such words are not available.

<P>

SP@  ( -- addr )  returns the
address corresponding to the top of data stack.

<P>

SP!  ( addr -- )  sets the stack pointer to addr, thus restoring the stack
depth to the same depth that existed just before addr was acquired by
executing SP@.

<P>

RP@  ( -- addr )  returns the address corresponding to the top of return
stack.

<P>

RP!  ( addr -- )  sets the return stack pointer to addr, thus restoring the
return stack depth to the same depth that existed just before addr was
acquired by executing RP@.

<PRE>
VARIABLE HANDLER   0 HANDLER !  \ last exception handler

: CATCH  ( xt -- exception# | 0 ) \ return addr on stack
    SP@ >R         ( xt ) \ save data stack pointer
    HANDLER @ >R   ( xt ) \ and previous handler
    RP@ HANDLER !  ( xt ) \ set current handler
    EXECUTE        ( )    \ execute returns if no THROW
    R> HANDLER !   ( )    \ restore previous handler
    R> DROP        ( )    \ discard saved stack ptr
    0              ( 0 )  \ normal completion
;

: THROW  ( ??? exception# -- ??? exception# )
    ?DUP IF          ( exc# ) \ 0 THROW is no-op
    HANDLER @ RP!  ( exc# ) \ restore prev return stack
    R> HANDLER !   ( exc# ) \ restore prev handler
    R> SWAP >R     ( saved-sp ) \ exc# on return stack
    SP! DROP R>    ( exc# ) \ restore stack
        \  Return to the caller of CATCH because return
        \  stack is restored to the state that existed
        \  when CATCH began execution
THEN
;
</PRE>

<P>

In a multi-tasking system, the HANDLER variable should be in the
per-task variable area (i.e., a user variable).

<P>

This sample implementation does not explicitly handle the case in which
CATCH has never been called (i.e., the ABORT behavior).  One solution is
to add the following code after the IF in THROW:


<PRE>
	HANDLER @ 0= IF ( empty the stack ) QUIT THEN
</PRE>

<P>

Another solution is to execute CATCH within 
<a href=dpans6.htm#6.1.2050>QUIT</a>, so that there is
always an <B>exception handler of last resort</B> present.  For example:

<PRE>
: QUIT      ( empty the return stack and )
            ( set the input source to the user input device )
    POSTPONE [
    BEGIN
      REFILL
    WHILE
      ['] INTERPRET CATCH
      CASE
      0 OF STATE @ 0= IF ." OK" THEN CR  ENDOF
     -1 OF ( Aborted) ENDOF
     -2 OF ( display  message from ABORT" ) ENDOF
      ( default ) DUP ." Exception # "  .
      ENDCASE
    REPEAT BYE
;
</PRE>

<P>

This example assumes the existance of a system-implementation word
INTERPRET that embodies the text interpreter semantics described in 
<a href=dpans3.htm#3.4>3.4</a>
The Forth text interpreter.  Note that this implementation of QUIT
automatically handles the emptying of the stack and return stack, due to
THROW's inherent restoration of the data and return stacks.  Given this
definition of QUIT, it's easy to define:


<PRE>
	: ABORT  -1 THROW ;
</PRE>

<P>

In systems with other stacks in addition to the data and return stacks,
the implementation of CATCH and THROW must save and restore those stack
pointers as well.  Such an <B>extended version</B> can be built on top
of this basic implementation.  For example, with another stack pointer
accessed with FP@ and FP! only CATCH needs to be redefined:

<PRE>
: CATCH  ( xt -- exception# | 0 )
    FP@ >R  CATCH  R> OVER IF FP! ELSE DROP THEN ;
</PRE>

<P>

No change to THROW is necessary in this case.  Note that, as with all
redefinitions, the redefined version of CATCH will only be available to
definitions compiled after the redefinition of CATCH.

<P>

CATCH and THROW provide a convenient way for an implementation to
<B>clean up</B> the state of open files if an exception occurs during
the text interpretation of a file with 
<a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a>.  The implementation
of INCLUDE-FILE may guard (with CATCH) the word that performs the text
interpretation, and if CATCH returns an exception code, the file may be
closed and the exception reTHROWn so that the files being included at an
outer nesting level may be closed also.  Note that the Standard allows,
but does not require, INCLUDE-FILE to close its open files if an
exception occurs.  However, it does require INCLUDE-FILE to unnest the
input source specification if an exception is THROWn.

<P>

<hr>
<a name=A.9.3>
<H3>A.9.3 Additional usage requirements</H3>
</a>

One important use of an exception handler is to maintain program control
under many conditions which 
<a href=dpans6.htm#6.1.0670>ABORT</a>.  This is practicable only if a range
of codes is reserved.  Note that an application may overload many
standard words in such a way as to 
<a href=dpans9.htm#9.6.1.2275>THROW</a> ambiguous conditions not
normally THROWn by a particular system.

<P>

<hr>
<a name=A.9.3.6>
<H4>A.9.3.6 Exception handling</H4>
</a>

The method of accomplishing this coupling is implementation dependent.
For example, 
<a href=dpans7.htm#7.6.1.1790>LOAD</a> 
could <B>know</B> about 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> and 
<a href=dpans9.htm#9.6.1.2275>THROW</a> (by using
CATCH itself, for example), or CATCH and THROW could <B>know</B> about
LOAD (by maintaining input source nesting information in a data
structure known to THROW, for example).  Under these circumstances it is
not possible for a Standard Program to define words such as LOAD in a
completely portable way.

<P>

<hr>
<a name=A.9.6>
<H3>A.9.6 Glossary</H3>
</a>


<hr>
<a name=A.9.6.1.2275>A.9.6.1.2275 THROW</A>
<P>

If THROW is executed with a non zero argument, the effect is as if the
corresponding 
<a href=dpans9.htm#9.6.1.0875>CATCH</a> 
had returned it.  In that case, the stack depth is
the same as it was just before CATCH began execution.  The values of the
i*x stack arguments could have been modified arbitrarily during the
execution of xt.  In general, nothing useful may be done with those
stack items, but since their number is known (because the stack depth is
deterministic), the application may 
<a href=dpans6.htm#6.1.1260>DROP</a> them to return to a predictable
stack state.

<P>

Typical use:

<PRE>
: could-fail ( -- char )
    KEY DUP [CHAR] Q =  IF  1 THROW THEN ;

: do-it ( a b -- c)   2DROP could-fail ;

: try-it ( --)
    1 2 ['] do-it  CATCH  IF ( x1 x2 )
        2DROP ." There was an exception" CR
    ELSE ." The character was " EMIT CR
    THEN
;

: retry-it ( -- )
    BEGIN  1 2 ['] do-it CATCH  WHILE
       ( x1 x2) 2DROP  ." Exception, keep trying" CR
    REPEAT ( char )
    ." The character was " EMIT CR
;
</PRE>

<P>

<hr>
<a href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<a href=dpansa10.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansb.htm/     850790280   500   0     100644  4638      `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansa.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansc.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=B.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>B. Bibliography (informative annex)</H1>


<hr>
<A name=Industry.standards>
<H3>Industry standards</H3>
</a>

Forth-77 Standard, Forth Users Group, FST-780314.

<P>

Forth-78 Standard,
Forth International Standards Team.

<P>

Forth-79 Standard, Forth Standards Team.

<P>

Forth-83 Standard and Appendices, Forth Standards Team.

<P>

The standards referenced in this section were developed by the Forth
Standards Team, a volunteer group which included both implementors and
users.  This was a volunteer organization operating under its own
charter and without any formal ties to ANSI, IEEE or any similar
standards body.  Several members of the Forth Standards Team have also
been members of the X3J14 Technical Committee.

<P>


<hr>
<a name=Books>
<H3>Books</H3>
</a>

Brodie, L.  <I>Starting FORTH (2nd ed).</I>
Englewood Cliffs, NJ:  Prentice Hall,
1987.

<P>

Brodie, L.  <I>Thinking FORTH.</I>
Englewood Cliffs, NJ:  Prentice Hall, 1984.

<P>

Feierbach, G.  and Thomas, P.  <I>Forth Tools & Applications.</I>
Reston, VA: Reston Computer Books, 1985.

<P>

Haydon, Dr.  Glen B.  <I>All About FORTH, Third Edition.</I>
La Honda, CA: 1990.

<P>

Kelly, Mahlon G. and Spies, N.  <I>FORTH: A Text and Reference.</I>
Englewood Cliffs, NJ: Prentice Hall, 1986.

<P>

Knecht, K.  <i>Introduction to Forth.</i>  Indiana: Howard Sams & Co.,
1982.

<P>

Koopman, P.  <I>Stack Computers, The New Wave.</I>
Chichester, West Sussex,
England: Ellis Horwood Ltd.  1989

<P>

Martin, Thea, editor.  <I>A Bibliography of Forth References, Third
Edition.</I> Rochester, New York: Institute of Applied Forth Research,
1987.

<P>

McCabe, C.  K.  <I>Forth Fundamentals (2 volumes/).</I>
Oregon: Dilithium Press, 1983.

<P>

Pountain, R.  <I>Object Oriented Forth.</I>
London, England: Academic Press, 1987.

<P>

Ouverson, Marlin, editor.  <I>Dr. Dobbs Toolbook of Forth.</I>
Redwood City, CA: M&T Press, Vol.  1, 1986; Vol.  2, 1987.

<P>

Terry, J.  D.  <I>Library of Forth Routines and Utilities.</I>
New York: Shadow Lawn Press, 1986

<P>

Tracy, M. and Anderson, A.  <I>Mastering FORTH (revised ed).</I>
New York: Brady Books, 1989.

<P>

Winfield, A. <I>The Complete Forth.</I>
New York: Wiley Books, 1983.

<P>

<hr>
<a name=Journals>
<H3>Journals, magazines and newsletters</H3>
</a>

Forsley, Lawrence P., Conference Chairman.  Rochester Forth Conference
Proceedings.  Rochester, New York: Institute of Applied Forth Research,
1981 to present.

<P>

Forsley, Lawrence P., Editor-in-Chief.  The Journal of Forth Application
and Research.  Rochester, New York: Institute of Applied Forth Research,
1983 to present.

<P>

Frenger, Paul, editor.  SIGForth Newsletter.  New York, NY: Association
for Computing Machinery, 1989 to present.

<P>

Ouverson, Marlin, editor.  Forth Dimensions.  San Jose, CA: The Forth
Interest Group, 1978 to present.

<P>

Reiling, Robert, editor.  FORML Conference Proceedings.  San Jose, CA:
The Forth Interest Group, 1980 to present.

<P>

Ting, Dr.  C.  H., editor.  More on Forth Engines.  San Mateo, CA:
Offete Enterprises, 1986 to present.

<P>


<hr>
<A name=Selected.articles>
<H3>Selected articles</H3>
</a>

Hayes, J.R.  <B>Postpone</B> Proceedings of the 1989 Rochester Forth
Conference.  Rochester, New York: Institute for Applied Forth Research,
1989.

<P>

Kelly, Guy M.  <B>Forth.</B> McGraw-Hill Personal Computer Programming
Encyclopedia - Languages and Operation Systems.  New York: McGraw-Hill,
1985.

<P>

Kogge, P.  M.  <B>An Architectural Trail to Threaded Code Systems.</B>
IEEE Computer (March, 1982).

<P>

Moore, C.  H.  <B>The Evolution of FORTH - An Unusual Language.</B> Byte
(August 1980).

<P>

Rather, E.  D.  <B>Forth Programming Language.</B> Encyclopedia of
Physical Science & Technology (Vol.  5).  New York: Academic Press,
1987.

<P>

Rather, E.  D.  <B>FORTH.</B> Computer Programming Management.  Auerbach
Publishers, Inc., 1985.

<P>

Rather, E.  D.; Colburn, D.  R.; Moore, C.  H.  <B>The Evolution of
FORTH.</B> ACM SIGPLAN Notices.  (Vol.  28, No.  3, March 1993).



<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansc.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpansc.htm/     845512560   500   0     100644  38079     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansb.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansd.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=C.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>C. Perspective (informative annex)</H1>

The purpose of this section is to provide an informal overview of Forth as a
language, illustrating its history, most prominent features, usage, and common
implementation techniques.  Nothing in this section should be considered as
binding upon either implementors or users.  A list of books and articles is
given in Annex B for those interested in learning more about Forth.

<P>

<hr>
<A name=C.1>
<H2>C.1 Features of Forth</H2>
</a>

Forth provides an interactive programming environment.  Its primary uses have
been in scientific and industrial applications such as instrumentation,
robotics, process control, graphics and image processing, artificial
intelligence and business applications.  The principal advantages of Forth
include rapid, interactive software development and efficient use of computer
hardware.

<P>

Forth is often spoken of as a language because that is its most visible
aspect.  But in fact, Forth is both more and less than a conventional
programming language:  more in that all the capabilities normally associated
with a large portfolio of separate programs (compilers, editors, etc.) are
included within its range and less in that it lacks (deliberately) the complex
syntax characteristic of most high-level languages.

<P>

The original implementations of Forth were stand-alone systems that included
functions normally performed by separate operating systems, editors,
compilers, assemblers, debuggers and other utilities.  A single simple,
consistent set of rules governed this entire range of capabilities.  Today,
although very fast stand-alone versions are still marketed for many
processors, there are also many versions that run co-resident with
conventional operating systems such as MS-DOS and UNIX.

<P>

Forth is not derived from any other language.  As a result, its appearance and
internal characteristics may seem unfamiliar to new users.  But Forth's
simplicity, extreme modularity, and interactive nature offset the initial
strangeness, making it easy to learn and use.  A new Forth programmer must
invest some time mastering its large command repertoire.  After a month or so
of full-time use of Forth, that programmer could understand more of its
internal working than is possible with conventional operating systems and
compilers.

<P>

The most unconventional feature of Forth is its extensibility.  The
programming process in Forth consists of defining new <B>words</B> -
actually new commands in the language.  These may be defined in terms of
previously defined words, much as one teaches a child concepts by
explaining them in terms of previously understood concepts.  Such words
are called <B>high-level definitions</B>.  Alternatively, new words may
also be defined in assembly code, since most Forth implementations
include an assembler for the host processor.

<P>

This extensibility facilitates the development of special application
languages for particular problem areas or disciplines.

<P>

Forth's extensibility goes beyond just adding new commands to the language.
With equivalent ease, one can also add new kinds of words.  That is, one may
create a word which itself will define words.  In creating such a defining
word the programmer may specify a specialized behavior for the words it will
create which will be effective at compile time, at run-time, or both.  This
capability allows one to define specialized data types, with complete control
over both structure and behavior.  Since the run-time behavior of such words
may be defined either in high-level or in code, the words created by this new
defining word are equivalent to all other kinds of Forth words in performance.
Moreover, it is even easy to add new compiler directives to implement special
kinds of loops or other control structures.

<P>

Most professional implementations of Forth are written in Forth.  Many
Forth systems include a <B>meta-compiler</B> which allows the user to
modify the internal structure of the Forth system itself.

<P>

<hr>
<A name=C.2>
<H2>C.2 History of Forth</H2>
</a>

Forth was invented by Charles H. Moore.  A direct outgrowth of Moore's work in
the 1960's, the first program to be called Forth was written in about 1970.
The first complete implementation was used in 1971 at the National Radio
Astronomy Observatory's 11-meter radio telescope in Arizona.  This system was
responsible for pointing and tracking the telescope, collecting data and
recording it on magnetic tape, and supporting an interactive graphics terminal
on which an astronomer could analyze previously recorded data.  The
multi-tasking nature of the system allowed all these functions to be performed
concurrently, without timing conflicts or other interference - a very advanced
concept for that time.

<P>

The system was so useful that astronomers from all over the world began asking
for copies.  Its use spread rapidly, and in 1976 Forth was adopted as a
standard language by the International Astronomical Union.

<P>

In 1973, Moore and colleagues formed FORTH, Inc.  to explore commercial
uses of the language.  FORTH, Inc.  developed multi-user versions of
Forth on minicomputers for diverse projects ranging from data bases to
scientific applications such as image processing.  In 1977, FORTH, Inc.
developed a version for the newly introduced 8-bit microprocessors
called <B>microFORTH</B>, which was successfully used in embedded
microprocessor applications in the United States, Britain and Japan.

<P>

Stimulated by the volume marketing of microFORTH, a group of computer
hobbyists in Northern California became interested in Forth, and in 1978
formed the Forth Interest Group (FIG).  They developed a simplified model
which they implemented on several microprocessors and published listings and
disks at very low cost.  Interest in Forth spread rapidly, and today there are
chapters of the Forth Interest Group throughout the U.S. and in over fifteen
countries.

<P>

By 1980, a number of new Forth vendors had entered the market with versions of
Forth based upon the FIG model.  Primarily designed for personal computers,
these relatively inexpensive Forth systems have been distributed very widely.

<P>


<hr>
<A name=C.3>
<H2>C.3 Hardware implementations of Forth</H2>
</a>

The internal architecture of Forth simulates a computer with two stacks, a set
of registers, and other standardized features.  As a result, it was almost
inevitable that someone would attempt to build a hardware representation of an
actual Forth computer.

<P>

In the early 1980's, Rockwell produced a 6502-variant with Forth primitives in
on-board ROM, the Rockwell 65F11.  This chip has been used successfully in
many embedded microprocessor applications.  In the mid-1980's Zilog developed
the z8800 (Super8) which offered ENTER (nest), EXIT (unnest) and NEXT in
microcode.

<P>

In 1981, Moore undertook to design a chip-level implementation of the Forth
virtual machine.  Working first at FORTH, Inc. and subsequently with the
start-up company NOVIX, formed to develop the chip, Moore completed the design
in 1984, and the first prototypes were produced in early 1985.  More recently,
Forth processors have been developed by Harris Semiconductor Corp., Johns
Hopkins University, and others.

<P>



<hr>
<A name=C.4>
<H2>C.4 Standardization efforts</H2>
</a>

The first major effort to standardize Forth was a meeting in Utrecht in 1977.
The attendees produced a preliminary standard, and agreed to meet the
following year.  The 1978 meeting was also attended by members of the newly
formed Forth Interest Group.  In 1979 and 1980 a series of meetings attended
by both users and vendors produced a more comprehensive standard called
Forth-79.

<P>

Although Forth-79 was very influential, many Forth users and vendors found
serious flaws in it, and in 1983 a new standard called Forth-83 was released.

<P>

Encouraged by the widespread acceptance of Forth-83, a group of users and
vendors met in 1986 to investigate the feasibility of an American National
Standard.  The X3J14 Technical Committee for ANS Forth held its first meeting
in 1987.  This Standard is the result.

<P>


<hr>
<A name=C.5>
<H2>C.5 Programming in Forth</H2>
</a>

Forth is an English-like language whose elements (called <B>words</B>)
are named data items, procedures, and defining words capable of creating
data items with customized characteristics.  Procedures and defining
words may be defined in terms of previously defined words or in machine
code, using an embedded assembler.

<P>

Forth <B>words</B> are functionally analogous to subroutines in other
languages.  They are also equivalent to commands in other languages -
Forth blurs the distinction between linguistic elements and functional
elements.

<P>

Words are referred to either from the keyboard or in program source by
name.  As a result, the term <B>word</B> is applied both to program (and
linguistic) units and to their text names.  In parsing text, Forth
considers a word to be any string of characters bounded by spaces.
There are a few special characters that cannot be included in a word or
start a word: space (the universal delimiter), CR (which ends terminal
input), and backspace or DEL (for backspacing during keyboard input).
Many groups adopt naming conventions to improve readability.  Words
encountered in text fall into three categories: defined words (i.e.,
Forth routines), numbers, and undefined words.  For example, here are
four words:


<PRE>
	<a href=dpans6.htm#6.1.1650>HERE</a>      <a href=dpans6.htm#6.1.1250>DOES></a>      <a href=dpans6.htm#6.1.0010>!</a>      8493
</PRE>

<P>

The first three are standard-defined words.  This means that they have
entries in Forth's dictionary, described below, explaining what Forth is
to do when these words are encountered.  The number <B>8493</B> will
presumably not be found in the dictionary, and Forth will convert it to
binary and place it on its push-down stack for parameters.  When Forth
encounters an undefined word and cannot convert it to a number, the word
is returned to the user with an exception message.

<P>

Architecturally, Forth words adhere strictly to the principles of
<B>structured programming</B>:

<UL>
<LI>Words must be defined before they are used.
<LI>Logical flow is restricted to sequential, conditional, and
iterative patterns. Words are included to implement the most useful
program control structures.
<LI>The programmer works with many small, independent modules
(words) for maximum testability and reliability.
</UL>
<P>

Forth is characterized by five major elements: a dictionary, two
push-down stacks, interpreters, an assembler, and virtual storage.
Although each of these may be found in other systems, the combination
produces a synergy that yields a powerful and flexible system.

<P>


<hr>
<A name=C.5.1>
<H3>C.5.1 The Forth dictionary</H3>
</a>

A Forth program is organized into a dictionary that occupies most of the
memory used by the system.  This dictionary is a threaded list of
variable-length items, each of which defines a word.  The content of
each definition depends upon the type of word (data item, constant,
sequence of operations, etc.).  The dictionary is extensible, usually
growing toward high memory.  On some multi-user systems individual users
have private dictionaries, each of which is connected to a shared system
dictionary.

<P>

Words are added to the dictionary by <B>defining words</B>, of which the
most commonly used is : 
(<a href=dpans6.htm#6.1.0450>colon</a>).  
When : is executed, it constructs a
definition for the word that follows it.  In classical implementations,
the content of this definition is a string of addresses of previously
defined words which will be executed in turn whenever the word being
defined is invoked.  The definition is terminated by ; 
(<a href=dpans6.htm#6.1.0460>semicolon</a>).  
For
example, here is a definition:


<PRE>
	: RECEIVE  ( -- addr n )  PAD DUP 32 ACCEPT ;
</PRE>

<P>

The name of the new word is RECEIVE.  The comment (in parentheses)
indicates that it requires no parameters and will return an address and
count on the data stack.  When RECEIVE is executed, it will perform the
words in the remainder of the definition in sequence.  The word 
<a href=dpans6.htm#6.2.2000>PAD</a>
places on the stack the address of a scratch pad used to handle strings.
<a href=dpans6.htm#6.1.1290>DUP</a> 
duplicates the top stack item, so we now have two copies of the
address.  The number 32 is also placed on the stack.  The word 
<a href=dpans6.htm#6.1.0695>ACCEPT</a>
takes an address (provided by PAD) and length (32) on the stack, accepts
from the keyboard a string of up to 32 characters which will be placed
at the specified address, and returns the number of characters received.
The copy of the scratch-pad address remains on the stack below the count
so that the routine that called RECEIVE can use it to pick up the
received string.

<P>


<hr>
<A name=C.5.2>
<H3>C.5.2 Push-down stacks</H3>
</a>

The example above illustrates the use of push-down stacks for passing
parameters between Forth words.  Forth maintains two push-down stacks,
or LIFO lists.  These provide communication between Forth words plus an
efficient mechanism for controlling logical flow.  A stack contains
16-bit items on 8-bit and 16-bit computers, and 32-bit items on 32-bit
processors.  Double-cell numbers occupy two stack positions, with the
most-significant part on top.  Items on either stack may be addresses or
data items of various kinds.  Stacks are of indefinite size, and usually
grow towards low memory.

<P>

Although the structure of both stacks is the same, they have very
different uses.  The user interacts most directly with the Data Stack,
which contains arguments passed between words.  This function replaces
the calling sequences used by conventional languages.  It is efficient
internally, and makes routines intrinsically re-entrant.  The second
stack is called the Return Stack, as its main function is to hold return
addresses for nested definitions, although other kinds of data are
sometimes kept there temporarily.

<P>

The use of the Data Stack (often called just <B>the stack</B>) leads to
a notation in which operands precede operators.  The word 
<a href=dpans6.htm#6.1.0695>ACCEPT</a> 
in the
example above took an address and count from the stack and left another
address there.  Similarly, a word called 
<a href=dpans17.htm#17.6.1.0780>BLANK</a> 
expects an address and
count, and will place the specified number of space characters (20H) in
the region starting at that address.  Thus,


<PRE>
	PAD 25 BLANK
</PRE>

<P>

will fill the scratch region whose address is pushed on the stack by 
<a href=dpans6.htm#6.2.2000>PAD</a>
with 25 spaces.  Application words are usually defined to work
similarly.  For example,


<PRE>
	100 SAMPLES
</PRE>

<P>

might be
defined to record 100 measurements in a data array.

<P>

Arithmetic operators also expect values and leave results on the stack.
For example, 
<a href=dpans6.htm#6.1.0120>+</a> 
adds the top two numbers on the stack, replacing them
both by their sum.  Since results of operations are left on the stack,
operations may be strung together without a need to define variables to
use for temporary storage.

<P>


<hr>
<A name=C.5.3>
<H3>C.5.3 Interpreters</H3>
</a>

Forth is traditionally an interpretive system, in that program execution
is controlled by data items rather than machine code.  Interpreters can
be slow, but Forth maintains the high speed required of real-time
applications by having two levels of interpretation.

<P>

The first is the text interpreter, which parses strings from the
terminal or mass storage and looks each word up in the dictionary.  When
a word is found it is executed by invoking the second level, the address
interpreter.

<P>

The second is an <B>address interpreter</B>.  Although not all Forth
systems are implemented in this way, it was the first and is still the
primary implementation technology.  For a small cost in performance, an
address interpreter can yield a very compact object program, which has
been a major factor in Forth's wide acceptance in embedded systems and
other applications where small object size is desirable.

<P>

The address interpreter processes strings of addresses or tokens
compiled in definitions created by : 
(<a href=dpans6.htm#6.1.0450>colon</a>), 
by executing the
definition pointed to by each.  The content of most definitions is a
sequence of addresses of previously defined words, which will be
executed by the address interpreter in turn.  Thus, when the word
RECEIVE (defined above) is executed, the word 
<a href=dpans6.htm#6.2.2000>PAD</a>, 
the word 
<a href=dpans6.htm#6.1.1290>DUP</a>, the
literal 32, and the word 
<a href=dpans6.htm#6.1.0695>ACCEPT</a> 
will be executed in sequence.  The
process is terminated by the 
semicolon.  This execution requires no
dictionary searches, parsing, or other logic, because when RECEIVE was
compiled the dictionary was searched for each word, and its address (or
other token) was placed in the next successive cell of the entry.  The
text was not stored in memory, not even in condensed form.

<P>

The address interpreter has two important properties.  First, it is
fast.  Although the actual speed depends upon the specific
implementation, professional implementations are highly optimized, often
requiring only one or two machine instructions per address.  On most
benchmarks, a good Forth implementation substantially out-performs
interpretive languages such as BASIC or LISP, and will compare favorably
with other compiled high-level languages.

<P>

Second, the address interpreter makes Forth definitions extremely
compact, as each reference requires only one cell.  In comparison, a
subroutine call constructed by most compilers involves instructions for
handling the calling sequence (unnecessary in Forth because of the
stack) before and after a CALL or JSR instruction and address.

<P>

Most of the words in a Forth dictionary will be defined by : (colon) and
interpreted by the address interpreter.  Most of Forth itself is defined
this way.

<P>


<hr>
<A name=C.5.4>
<H3>C.5.4 Assembler</H3>
</a>

Most implementations of Forth include a macro assembler for the CPU on
which they run.  By using the defining word 
<a href=dpans15.htm#15.6.2.0930>CODE</a> 
the programmer can
create a definition whose behavior will consist of executing actual
machine instructions.  CODE definitions may be used to do I/O, implement
arithmetic primitives, and do other machine-dependent or time-critical
processing.  When using CODE the programmer has full control over the
CPU, as with any other assembler, and CODE definitions run at full
machine speed.

<P>

This is an important feature of Forth.  It permits explicit
computer-dependent code in manageable pieces with specific interfacing
conventions that are machine-independent.  To move an application to a
different processor requires re-coding only the CODE words, which will
interact with other Forth words in exactly the same manner.

<P>

Forth assemblers are so compact (typically a few Kbytes) that they can
be resident in the system (as are the compiler, editor, and other
programming tools).  This means that the programmer can type in short
CODE definitions and execute them immediately.  This capability is
especially valuable in testing custom hardware.

<P>


<hr>
<A name=C.5.5>
<H3>C.5.5 Virtual memory</H3>
</a>

The final unique element of Forth is its way of using disk or other mass
storage as a form of <B>virtual memory</B> for data and program source.
As in the case of the address interpreter, this approach is historically
characteristic of Forth, but is by no means universal.  Disk is divided
into 1024-byte blocks.  Two or more buffers are provided in memory, into
which blocks are read automatically when referred to.  Each block has a
fixed block number, which in native systems is a direct function of its
physical location.  If a block is changed in memory, it will be
automatically written out when its buffer must be reused.  Explicit
reads and writes are not needed; the program will find the data in
memory whenever it accesses it.

<P>

Block-oriented disk handling is efficient and easy for native Forth
systems to implement.  As a result, blocks provide a completely
transportable mechanism for handling program source and data across both
native and co-resident versions of Forth on different host operating
systems.

<P>

Definitions in program source blocks are compiled into memory by the
word 
<a href=dpans7.htm#7.6.1.1790>LOAD</a>.  
Most implementations include an editor, which formats a
block for display into 16 lines of 64 characters each, and provides
commands modifying the source.  An example of a Forth source block is
given in Fig.  C.1 below.

<P>

Source blocks have historically been an important element in Forth
style.  Just as Forth definitions may be considered the linguistic
equivalent of sentences in natural languages, a block is analogous to a
paragraph.  A block normally contains definitions related to a common
theme, such as <B>vector arithmetic</B>.  A comment on the top line of
the block identifies this theme.  An application may selectively load
the blocks it needs.

<P>

Blocks are also used to store data.  Small records can be combined into
a block, or large records spread over several blocks.  The programmer
may allocate blocks in whatever way suits the application, and on native
systems can increase performance by organizing data to minimize disk
head motion.  Several Forth vendors have developed sophisticated file
and data base systems based on Forth blocks.

<P>

Versions of Forth that run co-resident with a host OS often implement
blocks in host OS files.  Others use the host files exclusively.  The
Standard requires that blocks be available on systems providing any disk
access method, as they are the only means of referencing disk that can
be transportable across both native and co-resident implementations.

<P>

<hr>
<a name=C.5.6>
<H3>C.5.6 Programming environment</H3>
</a>

Although this Standard does not require it, most Forth systems include a
resident editor.  This enables a programmer to edit source and recompile
it into executable form without leaving the Forth environment.  As it is
easy to organize an application into layers, it is often possible to
recompile only the topmost layer (which is usually the one currently
under development), a process which rarely takes more than a few
seconds.

<P>

Most Forth systems also provide resident interactive debugging aids, not
only including words such as those in 
<a href=dpans15.htm>15.</a> The optional
Programming-Tools word set, but also having the ability to examine and
change the contents of 
<a href=dpans6.htm#6.1.2410>VARIABLE</a>s 
and other data items and to execute
from the keyboard most of the component words in both the underlying
Forth system and the application under development.

<P>

The combination of resident editor, integrated debugging tools, and
direct executability of most defined words leads to a very interactive
programming style, which has been shown to shorten development time.

<P>


<hr>
<A name=C.5.7>
<H3>C.5.7 Advanced programming features</H3>
</a>

One of the unusual characteristics of Forth is that the words the
programmer defines in building an application become integral elements
of the language itself, adding more and more powerful
application-oriented features.

<P>

For example, Forth includes the words 
<a href=dpans6.htm#6.1.2410>VARIABLE</a> and 
<a href=dpans8.htm#8.6.1.0440>2VARIABLE</a> to name
locations in which data may be stored, as well as 
<a href=dpans6.htm#6.1.0950>CONSTANT</a> and 
<a href=dpans8.htm#8.6.1.0360>2CONSTANT</a>
to name single and double-cell values.  Suppose a programmer finds that
an application needs arrays that would be automatically indexed through
a number of two-cell items.  Such an array might be called 2ARRAY.  The
prefix <B>2</B> in the name indicates that each element in this array
will occupy two cells (as would the contents of a 2VARIABLE or
2CONSTANT).  The prefix <B>2</B>, however, has significance only to a
human and is no more significant to the text interpreter than any other
character that may be used in a definition name.

<P>

Such a definition has two parts, as there are two <B>behaviors</B>
associated with this new word 2ARRAY, one at compile time, and one at
run or execute time.  These are best understood if we look at how 2ARRAY
is used to define its arrays, and then how the array might be used in an
application.  In fact, this is how one would design and implement this
word.

<P>

Beginning the top-down design process, here's how we would like to use
2ARRAY:


<PRE>
	100 2ARRAY RAW   50 2ARRAY REFINED
</PRE>

<P>

In the first case, we are defining an array 100 elements long, whose
name is RAW.  In the second, the array is 50 elements long, and is named
REFINED.  In each case, a size parameter is supplied to 2ARRAY on the
data stack (Forth's text interpreter automatically puts numbers there
when it encounters them), and the name of the word immediately follows.
This order is typical of Forth defining words.

<P>

When we use RAW or REFINED, we would like to supply on the stack the
index of the element we want, and get back the address of that element
on the stack.  Such a reference would characteristically take place in a
loop.  Here's a representative loop that accepts a two-cell value from a
hypothetical application word DATA and stores it in the next element of
RAW:


<PRE>
	: ACQUIRE 100 0 DO DATA I RAW 2! LOOP ;
</PRE>

<P>

The name of this definition is ACQUIRE.  The loop begins with 
<a href=dpans6.htm#6.1.1240>DO</a>, ends
with 
<a href=dpans6.htm#6.1.1800>LOOP</a>, 
and will execute with index values running from 0 through 99.
Within the loop, DATA gets a value.  The word 
<a href=dpans6.htm#6.1.1680>I</a> 
returns the current
value of the loop index, which is the argument to RAW.  The address of
the selected element, returned by RAW, and the value, which has remained
on the stack since DATA, are passed to the word 
<a href=dpans6.htm#6.1.0310>2!</a> 
(pronounced
<B>two-store</B>), which stores two stack items in the address.

<P>

Now that we have specified exactly what 2ARRAY does and how the words it
defines are to behave, we are ready to write the two parts of its
definition:
<P>


<PRE>
	: 2ARRAY  ( n -- )
	   CREATE  2* CELLS ALLOT
	   DOES>  ( i a -- a')  SWAP  2*
	CELLS + ;
</PRE>

<P>

The part of the definition before the word 
<a href=dpans6.htm#6.1.1250>DOES></a> 
specifies the
<B>compile-time</B> behavior, that is, what the 2ARRAY will do when it
us used to define a word such as RAW.  The comment indicates that this
part expects a number on the stack, which is the size parameter.  The
word 
<a href=dpans6.htm#6.1.1000>CREATE</a> 
constructs the definition for the new word.  The phrase 
<a href=dpans6.htm#6.1.0320>2*</a>
<a href=dpans6.htm#6.1.0890>CELLS</a> 
converts the size parameter from two-cell units to the internal
addressing units of the system (normally characters).  
<a href=dpans6.htm#6.1.0710>ALLOT</a> 
then
allocates the specified amount of memory to contain the data to be
associated with the newly defined array.

<P>

The second line defines the <B>run-time</B> behavior that will be shared
by all words defined by 2ARRAY, such as RAW and REFINED.  The word DOES>
terminates the first part of the definition and begins the second part.
A second comment here indicates that this code expects an index and an
address on the stack, and will return a different address.  The index is
supplied on the stack by the caller (of RAW in the example), while the
address of the content of a word defined in this way (the ALLOTted
region) is automatically pushed on top of the stack before this section
of the code is to be executed.  This code works as follows: 
<a href=dpans6.htm#6.1.2260>SWAP</a>
reverses the order of the two stack items, to get the index on top.  2*
CELLS converts the index to the internal addressing units as in the
compile-time section, to yield an offset from the beginning of the
array.  The word 
<a href=dpans6.htm#6.1.0120>+</a> 
then adds the offset to the address of the start of
the array to give the effective address, which is the desired result.

<P>

Given this basic definition, one could easily modify it to do more
sophisticated things.  For example, the compile-time code could be
changed to initialize the array to zeros, spaces, or any other desired
initial value.  The size of the array could be compiled at its
beginning, so that the run-time code could compare the index against it
to ensure it is within range, or the entire array could be made to
reside on disk instead of main memory.  None of these changes would
affect the run-time usage we have specified in any way.  This
illustrates a little of the flexibility available with these defining
words.

<P>


<hr>
<A name=C.5.8>
<H3>C.5.8 A programming example</H3>
</a>

<a href=dpansc.htm#Figure.C.1>Figure C.1</a>
contains a typical block of Forth source.  It represents a
portion of an application that controls a bank of eight LEDs used as
indicator lamps on an instrument, and indicates some of the ways in
which Forth definitions of various kinds combine in an application
environment.  This example was coded for a STD-bus system with an 8088
processor and a millisecond clock, which is also used in the example.

<P>

The LEDs are interfaced through a single 8-bit port whose address is
40H.  This location is defined as a 
<a href=dpans6.htm#6.1.0950>CONSTANT</a> 
on Line 1, so that it may
be referred to by name; should the address change, one need only adjust
the value of this constant.  The word LIGHTS returns this address on the
stack.  The definition LIGHT takes a value on the stack and sends it to
the device.  The nature of this value is a bit mask, whose bits
correspond directly to the individual lights.

<P>

Thus, the command 255 LIGHT will turn on all lights, while 0 LIGHT will
turn them all off.

<P>

<a name=Figure.C.1>*</a>
<PRE>
Block 180
  0.      ( LED control )
  1.      HEX 40 CONSTANT LIGHTS DECIMAL
  2. : LIGHT ( n -- )  LIGHTS OUTPUT ;
  3.
  4. VARIABLE DELAY
  5. : SLOW  500 DELAY ! ;
  6. : FAST  100 DELAY ! ;
  7. : COUNTS 256 0 DO I LIGHT DELAY @ MS  LOOP ;
  8.
  9. : LAMP ( n -  )  CREATE ,  DOES> ( a -- n )   @ ;
 10. 1 LAMP POWER       2 LAMP HV     4 LAMP TORCH
 11. 8 LAMP SAMPLING   16 LAMP IDLING
 12.
 13. VARIABLE LAMPS
 14. : TOGGLE ( n -- ) LAMPS @ XOR DUP LAMPS ! LIGHT ;
 15.
</PRE>
<P>

Figure C.1 - Forth source block containing words that control a set of LEDs.

<P>

Lines 4 - 7 contain a simple diagnostic of the sort one might type in
from the terminal to confirm that everything is working.  The variable
DELAY contains a delay time in milliseconds - execution of the word
DELAY returns the address of this variable.  Two values of DELAY are set
by the definitions SLOW and FAST, using the Forth operator 
<a href=dpans6.htm#6.1.0010>!</a> 
(pronounced
<B>store</B>) which takes a value and an address, and stores the value
in the address.  The definition COUNTS runs a loop from 0 through 255
(Forth loops of this type are exclusive at the upper end of the range),
sending each value to the lights and then waiting for the period
specified by DELAY.  The word 
<a href=dpans6.htm#6.1.0650>@</a> 
(pronounced <B>fetch</B>) fetches a
value from an address, in this case the address supplied by DELAY.  This
value is passed to 
<a href=dpans10.htm#10.6.2.1905>MS</a>, 
which waits the specified number of milliseconds.
The result of executing COUNTS is that the lights will count from 0 to
255 at the desired rate.  To run this, one would type:


<PRE>
	SLOW COUNTS   or   FAST COUNTS
</PRE>

<P>

at the terminal.

<P>

Line 9 provides the capability of naming individual lamps.  In this
application they are being used as indicator lights.  The word LAMP is a
defining word which takes as an argument a mask which represents a
particular lamp, and compiles it as a named entity.  Lines 10 and 11
contain five uses of LAMP to name particular indicators.  When one of
these words such as POWER is executed, the mask is returned on the
stack.  In fact, the behavior of defining a value such that when the
word is invoked the value is returned, is identical to the behavior of a
Forth CONSTANT.  We created a new defining word here, however, to
illustrate how this would be done.

<P>

Finally, on lines 13 and 14, we have the words that will control the
light panel.  LAMPS is a variable that contains the current state of the
lamps.  The word TOGGLE takes a mask (which might be supplied by one of
the LAMP words) and changes the state of that particular lamp, saving
the result in LAMPS.

<P>

In the remainder of the application, the lamp names and TOGGLE are
probably the only words that will be executed directly.  The usage there
will be, for example:


<PRE>
	POWER TOGGLE   or   SAMPLING TOGGLE
</PRE>

<P>

as appropriate, whenever the system indicators need to be changed.

<P>

The time to compile this block of code on that system was about half a
second, including the time to fetch it from disk.  So it is quite
practical (and normal practice) for a programmer to simply type in a
definition and try it immediately.

<P>

In addition, one always has the capability of communicating with
external devices directly.  The first thing one would do when told about
the lamps would be to type:


<PRE>
	HEX FF 40 OUTPUT
</PRE>

<P>

and see if all the lamps come on.  If not, the presumption is that
something is amiss with the hardware, since this phrase directly
transmits the <B>all ones</B> mask to the device.  This type of direct
interaction is useful in applications involving custom hardware, as it
reduces hardware debugging time.

<P>


<hr>
<A name=C.6>
<H2>C.6 Multiprogrammed systems</H2>
</a>

Multiprogrammed Forth systems have existed since about 1970.  The
earliest public Forth systems propagated the <B>hooks</B> for this
capability despite the fact that many did not use them.  Nevertheless
the underlying assumptions have been common knowledge in the community,
and there exists considerable common ground among these multiprogrammed
systems.  These systems are not just language processors, but contain
operating system characteristics as well.  Many of these integrated
systems run entirely stand-alone, performing all necessary operating
system functions.

<P>

Some Forth systems are very fast, and can support both multi-tasking and
multi-user operation even on computers whose hardware is usually thought
incapable of such advanced operation.  For example, one producer of
telephone switchboards is running over 50 tasks on a Z80.  There are
several multiprogrammed products for PC's, some of which even support
multiple users.  Even on computers that are commonly used in multi-user
operations, the number of users that can be supported may be much larger
than expected.  One large data-base application running on a single
68000 has over 100 terminals updating and querying its data-base, with
no significant degradation.

<P>

Multi-user systems may also support multiple programmers, each of which
has a private dictionary, stacks, and a set of variables controlling
that task.  The private dictionary is linked to a shared, re-entrant
dictionary containing all the standard Forth functions.  The private
dictionary can be used to develop application code which may later be
integrated into the shared dictionary.  It may also be used to perform
functions requiring text interpretation, including compilation and
execution of source code.

<P>

<hr>
<A name=C.7>
<H2>C.7 Design and management considerations</H2>
</a>

Just as the choice of building materials has a strong effect on the
design and construction of a building, the choice of language and
operating system will affect both application design and project
management decisions.

<P>

Conventionally, software projects progress through four stages:
analysis, design, coding, and testing.  A Forth project necessarily
incorporates these activities as well.  Forth is optimized for a
project-management methodology featuring small teams of skilled
professionals.  Forth encourages an iterative process of <B>successive
prototyping</B> wherein high-level Forth is used as an executable design
tool, with <B>stubs</B> replacing lower-level routines as necessary
(e.g., for hardware that isn't built yet).

<P>

In many cases successive prototyping can produce a sounder, more useful
product.  As the project progresses, implementors learn things that
could lead to a better design.  Wiser decisions can be made if true
relative costs are known, and often this isn't possible until prototype
code can be written and tried.

<P>

Using Forth can shorten the time required for software development, and
reduce the level of effort required for maintenance and modifications
during the life of the product as well.

<P>


<hr>
<A name=C.8>
<H2>C.8 Conclusion</H2>
</a>

Forth has produced some remarkable achievements in a variety of
application areas.  In the last few years its acceptance has grown
rapidly, particularly among programmers looking for ways to improve
their productivity and managers looking for ways to simplify new
software-development projects.

<P>



<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansd.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansd.htm/     845512500   500   0     100644  39160     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansc.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpanse.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=D.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>D. Compatibility analysis of ANS Forth (informative annex)</H1>

Prior to ANS Forth, there were several industry standards for Forth.
The most influential are listed here in chronological order, along with
the major differences between ANS Forth and the most recent, Forth-83.

<P>


<hr>
<A name=D.1>
<H2>D.1 FIG Forth (circa 1978)</H2>
</a>

FIG Forth was a <B>model</B> implementation of the Forth language
developed by the Forth Interest Group (FIG).  In FIG Forth, a relatively
small number of words were implemented in processor-dependent machine
language and the rest of the words were implemented in Forth.  The FIG
model was placed in the public domain, and was ported to a wide variety
of computer systems.  Because the bulk of the FIG Forth implementation
was the same across all machines, programs written in FIG Forth enjoyed
a substantial degree of portability, even for <B>system-level</B>
programs that directly manipulate the internals of the Forth system
implementation.

<P>

FIG Forth implementations were influential in increasing the number of
people interested in using Forth.  Many people associate the
implementation techniques embodied in the FIG Forth model with <B>the
nature of Forth</B>.

<P>

However, FIG Forth was not necessarily representative of commercial
Forth implementations of the same era.  Some of the most successful
commercial Forth systems used implementation techniques different from
the FIG Forth <B>model</B>.

<P>


<hr>
<A name=D.2>
<H2>D.2 Forth-79</H2>
</a>

The Forth-79 Standard resulted from a series of meetings from 1978 to
1980, by the Forth Standards Team, an international group of Forth users
and vendors (interim versions known as Forth 77 and Forth 78 were also
released by the group).

<P>

Forth-79 described a set of words defined on a 16-bit, twos-complement,
unaligned, linear byte-addressing virtual machine.  It prescribed an
implementation technique known as <B>indirect threaded code</B>, and
used the ASCII character set.

<P>

The Forth-79 Standard served as the basis for several public domain and
commercial implementations, some of which are still available and
supported today.

<P>

<hr>
<A name=D.3>
<H2>D.3 Forth-83</H2>
</a>

The Forth-83 Standard, also by the Forth Standards Team, was released in
1983.  Forth-83 attempted to fix some of the deficiencies of Forth-79.

<P>

Forth-83 was similar to Forth-79 in most respects.  However, Forth-83
changed the definition of several well-defined features of Forth-79.
For example, the rounding behavior of integer division, the base value
of the operands of 
<a href=dpans6.htm#6.2.2030>PICK</a> 
and 
<a href=dpans6.htm#6.2.2150>ROLL</a>, 
the meaning of the address returned by
<a href=dpans6.htm#6.1.0070>'</a>, 
the compilation behavior of ', the value of a <B>true</B> flag, the
meaning of 
NOT, 
and the <B>chaining</B> behavior of words defined by
VOCABULARY were all changed.  Forth-83 relaxed the implementation
restrictions of Forth-79 to allow any kind of threaded code, but it did
not fully allow compilation to native machine code (this was not
specifically prohibited, but rather was an indirect consequence of
another provision).

<P>

Many new Forth implementations were based on the Forth-83 Standard, but
few <B>strictly compliant</B> Forth-83 implementations exist.

<P>

Although the incompatibilities resulting from the changes between
Forth-79 and Forth-83 were usually relatively easy to fix, a number of
successful Forth vendors did not convert their implementations to be
Forth-83 compliant.  For example, the most successful commercial Forth
for Apple Macintosh computers is based on Forth-79.

<P>

<hr>
<A name=D.4>
<H2>D.4 Recent developments</H2>
</a>

Since the Forth-83 Standard was published, the computer industry has
undergone rapid and profound changes.  The speed, memory capacity, and
disk capacity of affordable personal computers have increased by factors
of more than 100.  8-bit processors have given way to 16-bit processors,
and now 32-bit processors are commonplace.

<P>

The operating systems and programming-language environments of small
systems are much more powerful than they were in the early 80's.

<P>

The personal-computer marketplace has changed from a predominantly
<B>hobbyist</B> market to a mature business and commercial market.

<P>

Improved technology for designing custom microprocessors has resulted in
the design of numerous <B>Forth chips</B>, computers optimized for the
execution of the Forth language.

<P>

The market for ROM-based embedded control computers has grown
substantially.

<P>

In order to take full advantage of this evolving technology, and to
better compete with other programming languages, many recent Forth
implementations have ignored some of the <B>rules</B> of previous Forth
standards.  In particular:

<UL>
<LI>32-bit Forth implementations are now common.
<LI>Some Forth systems adopt the address-alignment restrictions of the
hardware on which they run.
<LI>Some Forth systems use native-code generation, microcode
generation, and optimization techniques, rather than the traditional
<B>threaded code</B>.
<LI>Some Forth systems exploit segmented addressing architectures,
placing portions of the Forth <B>dictionary</B> in different segments.
<LI>More and more Forth systems now run in the environment of
another <B>standard</B> operating system, using OS text files for source
code, rather than the traditional Forth <B>blocks</B>.
<LI>Some Forth systems allow external operating system software,
windowing software, terminal concentrators, or communications channels
to handle or preprocess user input, resulting in deviations from the
input editing, character set availability, and screen management
behavior prescribed by Forth-83.
</UL>
<P>

Competitive pressure from other programming languages (predominantly
<B>C</B>) and from other Forth vendors have led Forth vendors to
optimizations that do not fit in well with the <B>virtual machine
model</B> implied by existing Forth standards.

<P>


<hr>
<A name=D.5>
<H2>D.5 ANS Forth approach</H2>
</a>

The ANS Forth committee addressed the serious fragmentation of the Forth
community caused by the differences between Forth-79 and Forth-83, and
the divergence from either of these two industry standards caused by
marketplace pressures.

<P>

Consequently, the committee has chosen to base its compatibility
decisions not upon a strict comparison with the Forth-83 Standard, but
instead upon consideration of the variety of existing implementations,
especially those with substantial user bases and/or considerable success
in the marketplace.

<P>

The committee feels that, if ANS Forth prescribes stringent requirements
upon the virtual machine model, as did the previous standards, then many
implementors will chose not to comply with ANS Forth.  The committee
hopes that ANS Forth will serve to unify rather than to further divide
the Forth community, and thus has chosen to encompass rather than
invalidate popular implementation techniques.

<P>

Many of the changes from Forth-83 are justified by this rationale.  Most
fall into the category that <B>an ANS Forth Standard Program may not
assume x</B>, where <B>x</B> is an entitlement resulting from the
virtual machine model prescribed by the Forth-83 Standard.  The
committee feels that these restrictions are reasonable, especially
considering that a substantial number of existing Forth implementations
do not correctly implement the Forth-83 virtual model, thus the Forth-83
entitlements exist <B>in theory</B> but not <B>in practice</B>.

<P>

Another way of looking at this is that while ANS Forth acknowledges the
diversity of current Forth practice, it attempts to document the
similarity therein.  In some sense, ANS Forth is thus a <B>description
of reality</B> rather than a <B>prescription for a particular virtual
machine</B>.

<P>

Since there is no previous American National Standard for Forth, the
action requirements prescribed by section 3.4 of X3/SD-9, <B>Policy and
Guidelines</B>, regarding previous standards do not apply.

<P>

The following discussion describes differences between ANS Forth and
Forth-83.  In most cases, Forth-83 is representative of Forth-79 and FIG
Forth for the purposes of this discussion.  In many of these cases,
however, ANS Forth is more representative of the existing state of the
Forth industry than the previously-published standards.

<P>

<hr>
<A name=D.6>
<H2>D.6 Differences from Forth-83</H2>
</a>



<hr>
<A name=D.6.1>
<H3>D.6.1 Stack width</H3>
</a>

Forth-83 specifies that stack items occupy 16 bits.  This includes
addresses, flags, and numbers.  ANS Forth specifies that stack items are
at least 16 bits; the actual size must be documented by the
implementation.

<P>

Words affected:                 all arithmetic, logical and addressing
operators

<P>

Reason:                                 32-bit machines are becoming
commonplace.  A 16-bit Forth system on a 32-bit machine is not competitive.

<P>

Impact:                                 Programs that assume 16-bit stack
width will continue to run on 16-bit machines; ANS Forth does not require a
different stack width, but simply allows it.  Many programs will be unaffected
(but see <B>address unit</B>).

<P>

Transition/Conversion:  Programs which use bit masks with the high bits set
may have to be changed, substituting either an implementation-defined bit-mask
constant, or a procedure to calculate a bit mask in a stack-width-independent
way.  Here are some procedures for constructing width-independent bit masks:

<P>


<PRE>
1  CONSTANT LO-BIT
TRUE 1 RSHIFT  INVERT  CONSTANT HI-BIT

: LO-BITS  ( n -- mask )
    0 SWAP  0 ?DO  1 LSHIFT  LO-BIT OR  LOOP ;

: HI-BITS  ( n -- mask )
    0 SWAP  0 ?DO  1 RSHIFT  HI-BIT OR  LOOP ;
</PRE>

<P>

Programs that depend upon the <B>modulo 65536</B> behavior implicit in
16-bit arithmetic operations will need to be rewritten to explicitly
perform the modulus operation in the appropriate places.  The committee
believes that such assumptions occur infrequently.  Examples: some
checksum or CRC calculations, some random number generators and most
fixed-point fractional math.

<P>


<hr>
<A name=D.6.2>
<H3>D.6.2 Number representation</H3>
</a>

Forth-83 specifies two's-complement number representation and
arithmetic.  ANS Forth also allows one's-complement and
signed-magnitude.

<P>

Words affected: all arithmetic and logical operators, 
<a href=dpans6.htm#6.1.1800>LOOP</a>, 
<a href=dpans6.htm#6.1.0140>+LOOP</a>
<P>


Reason: Some computers use one's-complement or signed-magnitude.  The
committee did not wish to force Forth implementations for those machines
to emulate two's-complement arithmetic, and thus incur severe
performance penalties.  The experience of some committee members with
such machines indicates that the usage restrictions necessary to support
their number representations are not overly burdensome.

<P>

Impact: An ANS Forth Standard Program may declare an <B>environmental
dependency on two's-complement arithmetic</B>.  This means that the
otherwise-Standard Program is only guaranteed to work on
two's-complement machines.  Effectively, this is not a severe
restriction, because the overwhelming majority of current computers use
two's-complement.  The committee knows of no Forth-83 compliant
implementations for non-two's-complement machines at present, so
existing Forth-83 programs will still work on the same class of machines
on which they currently work.

<P>

Transition/Conversion: Existing programs wishing to take advantage of
the possibility of ANS Forth Standard Systems on non-two's-complement
machines may do so by eliminating the use of arithmetic operators to
perform logical functions, by deriving bit-mask constants from bit
operations as described in the section about stack width, by restricting
the usage range of unsigned numbers to the range of positive numbers,
and by using the provided operators for conversion from single numbers
to double numbers.

<P>


<hr>
<A name=D.6.3>
<H3>D.6.3 Address units</H3>
</a>

Forth-83 specifies that each unique address refers to an 8-bit byte in
memory.  ANS Forth specifies that the size of the item referred to by
each unique address is implementation-defined, but, by default, is the
size of one character.  Forth-83 describes many memory operations in
terms of a number of bytes.  ANS Forth describes those operations in
terms of a number of either characters or address units.

<P>

Words affected: those with <B>address unit</B> arguments
<P>

Reason: Some machines, including the most popular Forth chip, address
16-bit memory locations instead of 8-bit bytes.

<P>

Impact: Programs may choose to declare an environmental dependency on
byte addressing, and will continue to work on the class of machines for
which they now work.  In order for a Forth implementation on a
word-addressed machine to be Forth-83 compliant, it would have to
simulate byte addressing at considerable cost in speed and memory
efficiency.  The committee knows of no such Forth-83 implementations for
such machines, thus an environmental dependency on byte addressing does
not restrict a Standard Program beyond its current de facto
restrictions.

<P>

Transition/Conversion: The new 
<a href=dpans6.htm#6.1.0898>CHARS</a> 
and 
<a href=dpans6.htm#6.1.0897>CHAR+</a> 
address arithmetic
operators should be used for programs that require portability to
non-byte-addressed machines.  The places where such conversion is
necessary may be identified by searching for occurrences of words that
accept a number of address units as an argument (e.g., 
<a href=dpans6.htm#6.1.1900>MOVE</a>, 
<a href=dpans6.htm#6.1.0710>ALLOT</a>).

<P>


<hr>
<A name=D.6.4>
<H3>D.6.4 Address increment for a cell is no longer two</H3>
</a>

As a consequence of Forth-83's simultaneous specification of 16-bit
stack width and byte addressing, the number two could reliably be used
in address calculations involving memory arrays containing items from
the stack.  Since ANS Forth requires neither 16-bit stack width nor byte
addressing, the number two is no longer necessarily appropriate for such
calculations.

<P>

Words
affected: 
<a href=dpans6.htm#6.1.0650>@</a> 
<a href=dpans6.htm#6.1.0010>!</a> 
<a href=dpans6.htm#6.1.0130>+!</a> 
2+ 
<a href=dpans6.htm#6.1.0320>2*</a> 
2- 
<a href=dpans6.htm#6.1.0140>+LOOP</a>

<P>

Reason: See reasons for <B>Address Units</B> and <B>Stack Width</B>
<P>

Impact: In this respect, existing programs will continue to work on
machines where a stack cell occupies two address units when stored in
memory.  This includes most machines for which Forth-83 compliant
implementations currently exist.  In principle, it would also include
16-bit-word-addressed machines with 32-bit stack width, but the
committee knows of no examples of such machines.

<P>

Transition/Conversion: The new 
<a href=dpans6.htm#6.1.0890>CELLS</a> 
and 
<a href=dpans6.htm#6.1.0880>CELL+</a> 
address arithmetic
operators should be used for portable programs.  The places where such
conversion is necessary may be identified by searching for the character
<B>2</B> and determining whether or not it is used as part of an address
calculation.  The following substitutions are appropriate within address
calculations:

<P>


<PRE>
Old                     New
---                     ---
2+  or  2 +             CELL+
2*  or  2 *             CELLS
2-  or  2 -             1 CELLS -
2/  or  2 /             1 CELLS /
2                       1 CELLS
</PRE>

<P>

The number <B>2</B> by itself is sometimes used for address calculations
as an argument to 
+LOOP, 
when the loop index is an address.  When
converting the word 
<a href=dpans6.htm#6.1.0330>2/</a> 
which operates on negative dividends, one should
be cognizant of the rounding method used.

<P>


<hr>
<A name=D.6.5>
<H3>D.6.5 Address alignment</H3>
</a>

Forth-83 imposes no restriction upon the alignment of addresses to any
boundary.  ANS Forth specifies that a Standard System may require
alignment of addresses for use with various <B>@</B> and <B>!</B>
operators.

<P>

Words Affected: 
<a href=dpans6.htm#6.1.0010>!</a> 
<a href=dpans6.htm#6.1.0130>+!</a> 
<a href=dpans6.htm#6.1.0310>2!</a> 
<a href=dpans6.htm#6.1.0350>2@</a> 
<a href=dpans6.htm#6.1.0650>@</a> 
<a href=dpans15.htm#15.6.1.0600>?</a> 
<a href=dpans6.htm#6.1.0150>,</a>
<P>

Reason: Many computers have hardware restrictions that favor the use of
aligned addresses.  On some machines, the native memory-access
instructions will cause an exception trap if used with an unaligned
address.  Even on machines where unaligned accesses do not cause
exception traps, aligned accesses are usually faster.

<P>

Impact: All of the ANS Forth words that return addresses suitable for
use with aligned <B>@</B> and <B>!</B> words must return aligned
addresses.  In most cases, there will be no problem.  Problems can arise
from the use of user-defined data structures containing a mixture of
character data and cell-sized data.

<P>

Many existing Forth systems, especially those currently in use on
computers with strong alignment requirements, already require alignment.
Much existing Forth code that is currently in use on such machines has
already been converted for use in an aligned environment.

<P>

Transition/Conversion: There are two possible approaches to conversion
of programs for use on a system requiring address alignment.

<P>

The easiest approach is to redefine the system's aligned <B>@</B> and
<B>!</B> operators so that they do not require alignment.  For example,
on a 16-bit little-endian byte-addressed machine, unaligned <B>@</B> and
<B>!</B> could be defined:


<PRE>
	: @  ( addr -- x )  DUP C@ SWAP CHAR+ C@ 8 LSHIFT OR  ;
	: !  ( x addr -- )  OVER 8 RSHIFT OVER CHAR+ C! C!  ;
</PRE>
<P>

These definitions, and similar ones for <B>+!</B>, <B>2@</B>, <B>2!</B>,
<B>,</B>, and <B>?</B> as needed, can be compiled before an unaligned
application, which will then work as expected.

<P>

This approach may conserve memory if the application uses substantial
numbers of data structures containing unaligned fields.

<P>

Another approach is to modify the application's source code to eliminate
unaligned data fields.  The ANS Forth words 
<a href=dpans6.htm#6.1.0705>ALIGN</a> 
and 
<a href=dpans6.htm#6.1.0706>ALIGNED</a> 
may be
used to force alignment of data fields.  The places where such alignment
is needed may be determined by inspecting the parts of the application
where data structures (other than simple variables) are defined, or by
<B>smart compiler</B> techniques (see the <B>Smart Compiler</B>
discussion below).

<P>

This approach will probably result in faster application execution
speed, at the possible expense of increased memory utilization for data
structures.

<P>

Finally, it is possible to combine the preceding techniques by
identifying exactly those data fields that are unaligned, and using
<B>unaligned</B> versions of the memory access operators for only those
fields.  This <B>hybrid</B> approach affects a compromise between
execution speed and memory utilization.

<P>


<hr>
<a name=D.6.6>
<H3>D.6.6 Division/modulus rounding direction</H3>
</a>

Forth-79 specifies that division rounds toward 0 and the remainder
carries the sign of the dividend.  Forth-83 specifies that division
rounds toward negative infinity and the remainder carries the sign of
the divisor.  ANS Forth allows either behavior for the division
operators listed below, at the discretion of the implementor, and
provides a pair of division primitives to allow the user to synthesize
either explicit behavior.

<P>

Words Affected: 
<a href=dpans6.htm#6.1.0230>/</a> 
<a href=dpans6.htm#6.1.1890>MOD</a> 
<a href=dpans6.htm#6.1.0240>/MOD</a> 
<a href=dpans6.htm#6.1.0110>*/MOD</a> 
<a href=dpans6.htm#6.1.0100>*/</a>
<P>

Reason: The difference between the division behaviors in Forth-79 and
Forth-83 was a point of much contention, and many Forth implementations
did not switch to the Forth-83 behavior.  Both variants have vocal
proponents, citing both application requirements and execution
efficiency arguments on both sides.  After extensive debate spanning
many meetings, the committee was unable to reach a consensus for
choosing one behavior over the other, and chose to allow either behavior
as the default, while providing a means for the user to explicitly use
both behaviors as needed.  Since implementors are allowed to choose
either behavior, they are not required to change the behavior exhibited
by their current systems, thus preserving correct functioning of
existing programs that run on those systems and depend on a particular
behavior.  New implementations could choose to supply the behavior that
is supported by the native CPU instruction set, thus maximizing
execution speed, or could choose the behavior that is most appropriate
for the intended application domain of the system.

<P>

Impact: The issue only affects programs that use a negative dividend
with a positive divisor, or a positive dividend with a negative divisor.
The vast majority of uses of division occur with both a positive
dividend and a positive divisor; in that case, the results are the same
for both allowed division behaviors.

<P>

Transition/Conversion: For programs that require a specific rounding
behavior with division operands of mixed sign, the division operators
used by the program may be redefined in terms of one of the new ANS
Forth division primitives 
<a href=dpans6.htm#6.1.2214>SM/REM</a> 
(symmetrical division, i.e., round
toward zero) or 
<a href=dpans6.htm#6.1.1561>FM/MOD</a> 
(floored division, i.e., round toward negative
infinity).  Then the program may be recompiled without change.  For
example, the Forth-83 style division operators may be defined by:

<P>


<PRE>
: /MOD  ( n1 n2 -- n3 n4 )     >R S>D R> FM/MOD  ;
: MOD   ( n1 n2 -- n3 )        /MOD DROP  ;
: /     ( n1 n2 -- n3 )        /MOD SWAP DROP   ;
: */MOD ( n1 n2 n3 -- n4 n5 )  >R M* R> FM/MOD  ;
: */    ( n1 n2 n3 -- n4 n5 )  */MOD SWAP DROP  ;
</PRE>

<P>

<hr>
<A name=D.6.7>
<H3>D.6.7 Immediacy</H3>
</a>

Forth-83 specified that a number of <B>compiling words</B> are
<B>immediate</B>, meaning that they are executed instead of compiled
during compilation.  ANS Forth is less specific about most of these
words, stating that their behavior is only defined during compilation,
and specifying their results rather than their specific compile-time
actions.

<P>

To force the compilation of a word that would normally be executed,
Forth-83 provided the words COMPILE , used with non-immediate words, and
<a href=dpans6.htm#6.2.2530>[COMPILE]</a> , 
used with immediate words.  ANS Forth provides the single
word 
<a href=dpans6.htm#6.1.2033>POSTPONE</a> , 
which is used with both immediate and non-immediate
words, automatically selecting the appropriate behavior.

<P>

Words Affected: 
<b><code>COMPILE [COMPILE] 
<a href=dpans6.htm#6.1.2510>[']</a> 
<a href=dpans6.htm#6.1.0070>'</a></code></b>
<P>

Reason: The designation of particular words as either immediate or not
depends upon the implementation technique chosen for the Forth system.
With traditional <B>threaded code</B> implementations, the choice was
generally quite clear (with the single exception of the word 
<a href=dpans6.htm#6.1.1760>LEAVE</a>), and
the standard could specify which words should be immediate.  However,
some of the currently popular implementation techniques, such as
native-code generation with optimization, require the immediacy
attribute on a different set of words than the set of immediate words of
a threaded code implementation.  ANS Forth, acknowledging the validity
of these other implementation techniques, specifies the immediacy
attribute in as few cases as possible.

<P>

When the membership of the set of immediate words is unclear, the
decision about whether to use COMPILE or [COMPILE] becomes unclear.
Consequently, ANS Forth provides a <B>general purpose</B> replacement
word POSTPONE that serves the purpose of the vast majority of uses of
both COMPILE and [COMPILE], without requiring that the user know whether
or not the <B>postponed</B> word is immediate.

<P>

Similarly, the use of ' and ['] with compiling words is unclear if the
precise compilation behavior of those words is not specified, so ANS
Forth does not permit a Standard Program to use ' or ['] with compiling
words.

<P>

The traditional (non-immediate) definition of the word COMPILE has an
additional problem.  Its traditional definition assumes a threaded code
implementation technique, and its behavior can only be properly
described in that context.  In the context of ANS Forth, which permits
other implementation techniques in addition to threaded code, it is very
difficult, if not impossible, to describe the behavior of the
traditional COMPILE.  Rather than changing its behavior, and thus
breaking existing code, ANS Forth does not include the word COMPILE.
This allows existing implementations to continue to supply the word
COMPILE with its traditional behavior, if that is appropriate for the
implementation.

<P>

Impact: [COMPILE] remains in ANS Forth, since its proper use does not
depend on knowledge of whether or not a word is immediate (Use of
[COMPILE] with a non-immediate word is and has always been a no-op).
Whether or not you need to use [COMPILE] requires knowledge of whether
or not its target word is immediate, but it is always safe to use
[COMPILE].  [COMPILE] is no longer in the (required) core word set,
having been moved to the Core Extensions word set, but the committee
anticipates that most vendors will supply it anyway.

<P>

In nearly all cases, it is correct to replace both [COMPILE] and COMPILE
with POSTPONE.  Uses of [COMPILE] and COMPILE that are not suitable for
<B>mindless</B> replacement by POSTPONE are quite infrequent, and fall
into the following two categories:

<P>

a)      Use of [COMPILE] with non-immediate words.  This is sometimes done
with the words '-(tick, which was immediate in Forth-79 but not in Forth-83)
and LEAVE (which was immediate in Forth-83 but not in Forth-79), in order to
force the compilation of those words without regard to whether you are using a
Forth-79 or Forth-83 system.

<P>

b)      Use of the phrase  COMPILE [COMPILE] &lt;immediate word&gt; to
<B>doubly
postpone</B> an immediate word.

<P>

Transition/Conversion:  Many ANS Forth implementations will continue to
implement both [COMPILE] and COMPILE in forms compatible with existing usage.
In those environments, no conversion is necessary.

<P>

For complete portability, uses of COMPILE and [COMPILE] should be
changed to POSTPONE , except in the rare cases indicated above.  Uses of
[COMPILE] with non-immediate words may be left as-is, and the program
may declare a requirement for the word [COMPILE] from the Core
Extensions word set, or the [COMPILE] before the non-immediate word may
be simply deleted if the target word is known to be non-immediate.

<P>

Uses of the phrase COMPILE [COMPILE] &lt;immediate-word&gt; may be handled by
introducing an <B>intermediate word</B> (XX in the example below) and
then postponing that word.  For example:


<PRE>

	: ABC  COMPILE [COMPILE] IF  ;

</PRE>
<P>

changes to:
<P>


<PRE>
	: XX  POSTPONE IF  ;
	: ABC  POSTPONE XX  ;
</PRE>
<P>

A non-standard case can occur with programs that <B>switch out of
compilation state</B> to explicitly compile a thread in the dictionary
following a COMPILE .  For example:


<PRE>
	: XYZ  COMPILE  [ ' ABC , ]  ;
</PRE>
<P>

This depends heavily on knowledge of exactly how COMPILE and the
threaded-code implementation works.  Cases like this cannot be handled
mechanically; they must be translated by understanding exactly what the
code is doing, and rewriting that section according to ANS Forth
restrictions.

<P>

Use the phrase POSTPONE [COMPILE]
to replace [COMPILE] [COMPILE].

<P>

<hr>
<A name=D.6.8>
<H3>D.6.8 Input character set</H3>
</a>

Forth-83 specifies that the full 7-bit ASCII character set is available
through 
KEY.  
ANS Forth restricts it to the graphic characters of the
ASCII set, with codes from hex 20 to hex 7E inclusive.

<P>

Words Affected:                 
<a href=dpans6.htm#6.1.1750>KEY</a>
<P>

Reason: Many system environments <B>consume</B> certain control
characters for such purposes as input editing, job control, or flow
control.  A Forth implementation cannot always control this system
behavior.

<P>

Impact: Standard Programs which require the ability to receive
particular control characters through KEY must declare an environmental
dependency on the input character set.

<P>

Transition/Conversion: For maximum portability, programs should restrict
their required input character set to only the graphic characters.
Control characters may be handled if available, but complete program
functionality should be accessible using only graphic characters.

<P>

As stated above, an environmental dependency on the input character set
may be declared.  Even so, it is recommended that the program should
avoid the requirement for particularly-troublesome control characters,
such as control-S and control-Q (often used for flow control, sometimes
by communication hardware whose presence may be difficult to detect),
ASCII NUL (difficult to type on many keyboards), and the distinction
between carriage return and line feed (some systems translate carriage
returns into line feeds, or vice versa).

<P>

<hr>
<A name=D.6.9>
<H3>D.6.9 Shifting with UM/MOD</H3>
</a>

Given Forth-83's two's-complement nature, and its requirement for
floored (round toward minus infinity) division, shifting is equivalent
to division.  Also, two's-complement representation implies that
unsigned division by a power of two is equivalent to logical
right-shifting, so UM/MOD could be used to perform a logical
right-shift.

<P>

Words Affected: 
<a href=dpans6.htm#6.1.2370>UM/MOD</a>
<P>

Reason: The problem with UM/MOD is a result of allowing
non-two's-complement number representations, as already described.

<P>

ANS Forth provides the words 
<a href=dpans6.htm#6.1.1805>LSHIFT</a> and 
<a href=dpans6.htm#6.1.2162>RSHIFT</a> 
to perform logical
shifts.  This is usually more efficient, and certainly more descriptive,
than the use of UM/MOD for logical shifting.

<P>

Impact: Programs running on ANS Forth systems with two's-complement
arithmetic (the majority of machines), will not experience any
incompatibility with UM/MOD .  Existing Forth-83 Standard programs
intended to run on non-two's-complement machines will not be able to use
UM/MOD for shifting on a non-two's-complement ANS Forth system.  This
should not affect a significant number of existing programs (perhaps
none at all), since the committee knows of no existing Forth-83
implementations on non-two's-complement machines.

<P>

Transition/Conversion: A program that requires UM/MOD to behave as a
shift operation may declare an environmental dependency on
two's-complement arithmetic.

<P>

A program that cannot declare an environmental dependency on
two's-complement arithmetic may require editing to replace incompatible
uses of UM/MOD with other operators defined within the application.

<P>

<hr>
<A name=D.6.10>
<H3>D.6.10 Vocabularies / wordlists</H3>
</a>

ANS Forth does not define the words VOCABULARY, CONTEXT, and CURRENT ,
which were present in Forth-83.  Instead, ANS Forth defines a primitive
word set for search order specification and control, including words
which have not existed in any previous standard.

<P>

Forth-83's 
<a href=dpans16.htm#16.6.2.0715>ALSO</a>/<a href=dpans16.htm#16.6.2.1965>ONLY</a> 
experimental search order word set is
specified for the most part as the extension portion of the ANS Forth
Search Order word set.

<P>

Words Affected: 
<b><code>VOCABULARY CONTEXT CURRENT</code></b>
<P>

Reason: Vocabularies are an area of much divergence among existing
systems.  Considering major vendors' systems and previous standards,
there are at least 5 different and mutually incompatible behaviors of
words defined by VOCABULARY.  Forth-83 took a step in the direction of
<B>run-time search-order specification</B> by declining to specify a
specific relationship between the hierarchy of compiled vocabularies and
the run-time search order.  Forth-83 also specified an experimental
mechanism for run-time search-order specification, the ALSO/ONLY scheme.
ALSO/ONLY was implemented in numerous systems, and has achieved some
measure of popularity in the Forth community.

<P>

However, several vendors refuse to implement it, citing technical
limitations.  In an effort to address those limitations and thus
hopefully make ALSO/ONLY more palatable to its critics, the committee
specified a simple <B>primitive word set</B> that not only fixes some of
the objections to ALSO/ONLY, but also provides sufficient power to
implement ALSO/ONLY and all of the other search-order word sets that are
currently popular.

<P>

The Forth-83 ALSO/ONLY word set is provided as an optional extension to
the search-order word set.  This allows implementors that are so
inclined to provide this word set, with well-defined standard behavior,
but does not compel implementors to do so.  Some vendors have publicly
stated that they will not implement ALSO/ONLY, no matter what, and one
major vendor stated an unwillingness to implement ANS Forth at all if
ALSO/ONLY is mandated.  The committee feels that its actions are
prudent, specifying ALSO/ONLY to the extent possible without mandating
its inclusion in all systems, and also providing a primitive
search-order word set that vendors may be more likely to implement, and
which can be used to synthesize ALSO/ONLY.

<P>

Transition/Conversion: Since Forth-83 did not mandate precise semantics
for VOCABULARY, existing Forth-83 Standard programs cannot use it except
in a trivial way.  Programs can declare a dependency on the existence of
the Search Order word set, and can implement whatever semantics are
required using that word set's primitives.  Forth-83 programs that need
ALSO/ONLY can declare a dependency on the Search Order Extensions word
set, or can implement the extensions in terms of the Search Order word
set itself.

<P>

<hr>
<A name=D.6.11>
<H3>D.6.11 Multiprogramming impact</H3>
</a>

Forth-83 marked words with <B>multiprogramming impact</B> by the letter
<B>M</B> in the first lines of their descriptions.  ANS Forth has
removed the <B>M</B> designation from the word descriptions, moving the
discussion of multiprogramming impact to this non-normative annex.

<P>

Words affected: none
<P>

Reason: The meaning of <B>multiprogramming impact</B> is precise only in
the context of a specific model for multiprogramming.  Although many
Forth systems do provide multiprogramming capabilities using a
particular round-robin, cooperative, block-buffer sharing model, that
model is not universal.  Even assuming the classical model, the <B>M</B>
designations did not contain enough information to enable writing of
applications that interacted in a multiprogrammed system.

<P>

Practically speaking, the <B>M</B> designations in Forth-83 served to
document usage rules for block buffer addresses in multiprogrammed
systems.  These addresses often become meaningless after a task has
relinquished the CPU for any reason, most often for the purposes of
performing I/O, awaiting an event, or voluntarily sharing CPU resources
using the word PAUSE.  It was essential that portable applications
respect those usage rules to make it practical to run them on
multiprogrammed systems; failure to adhere to the rules could easily
compromise the integrity of other applications running on those systems
as well as the applications actually in error.  Thus, <B>M</B> appeared
on all words that by design gave up the CPU, with the understanding that
other words NEVER gave it up.

<P>

These usage rules have been explicitly documented in the Block word set
where they are relevant.  The <B>M</B> designations have been removed
entirely.

<P>

Impact: In practice, none.
<P>

In the sense that any application that depends on multiprogramming must
consist of at least two tasks that share some resource(s) and
communicate between themselves, Forth-83 did not contain enough
information to enable writing of a standard program that DEPENDED on
multiprogramming.  This is also true of ANS Forth.

<P>

Non-multiprogrammed applications in Forth-83 were required to respect
usage rules for 
<a href=dpans7.htm#7.6.1.0800>BLOCK</a> 
so that they could be run properly on
multiprogrammed systems.  The same is true of ANS Forth.

<P>

The only difference is the documentation method used to define the BLOCK
usage rules.  The Technical Committee believes that the current method
is clearer than the concept of <B>multiprogramming impact</B>.

<P>

Transition/Conversion:
none needed.

<P>

<hr>
<A name=D.6.12>
<H3>D.6.12 Words not provided in executable form</H3>
</a>

ANS Forth allows an implementation to supply some words in source code
or <B>load as needed</B> form, rather than requiring all supplied words
to be available with no additional programmer action.

<P>

Words affected: all
<P>

Reason: Forth systems are often used in environments where memory space
is at a premium.  Every word included in the system in executable form
consumes memory space.  The committee believes that allowing standard
words to be provided in source form will increase the probability that
implementors will provide complete ANS Forth implementations even in
systems designed for use in constrained environments.

<P>

Impact: In order to use a Standard Program with a given ANS Forth
implementation, it may be necessary to precede the program with an
implementation-dependent <B>preface</B> to make <B>source form</B> words
executable.  This is similar to the methods that other computer
languages require for selecting the library routines needed by a
particular application.

<P>

In languages like C, the goal of eliminating unnecessary routines from
the memory image of an application is usually accomplished by providing
libraries of routines, using a <B>linker</B> program to incorporate only
the necessary routines into an executable application.  The method of
invoking and controlling the linker is outside the scope of the language
definition.

<P>

Transition/Conversion: Before compiling a program, the programmer may
need to perform some action to make the words required by that program
available for execution.
<P>

<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpanse.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>
dpanse.htm/     845512500   500   0     100644  21265     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpansd.htm><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
<a href=dpansf.htm><img src=right.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=E.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>E. ANS Forth portability guide (informative
annex)</H1>


<hr>
<A name=E.1>
<H1>E.1 Introduction</H1>
</a>

The most popular architectures used to implement Forth have had
byte-addressed memory, 16-bit operations, and two's-complement number
representation. The Forth-83 Standard dictates that these particular
features must be present in a Forth-83 Standard system and that Forth-83
programs may exploit these features freely.

<P>

However, there are many beasts in the architectural jungle that are bit
addressed or cell addressed, or prefer 32-bit operations, or represent
numbers in one's complement. Since one of Forth's strengths is its
usefulness in <B>strange</B> environments on <B>unusual</B> hardware
with <B>peculiar</B> features, it is important that a Standard Forth run
on these machines too.

<P>

A primary goal of the ANS Forth Standard is to increase the types of
machines that can support a Standard Forth. This is accomplished by
allowing some key Forth terms to be implementation-defined (e.g., how
big is a cell?) and by providing Forth operators (words) that conceal
the implementation. This frees the implementor to produce the Forth
system that most effectively utilizes the native hardware. The machine
independent operators, together with some programmer discipline, enable
a programmer to write Forth programs that work on a wide variety of
machines.

<P>

The remainder of this Annex provides guidelines for writing portable ANS
Forth programs. The first section describes ways to make a program
hardware independent. It is difficult for someone familiar with only
one machine architecture to imagine the problems caused by transporting
programs between dissimilar machines. Consequently, examples of
specific architectures with their respective problems are given. The
second section describes assumptions about Forth implementations that
many programmers make, but can't be relied upon in a portable program.

<P>


<hr>
<A name=E.2>
<H1>E.2 Hardware peculiarities</H1>
</a>


<hr>
<A name=E.2.1>
<H2>E.2.1 Data/memory abstraction</H2>
</a>

Data and memory are the stones and mortar of program construction.
Unfortunately, each computer treats data and memory differently. The
ANS Forth Systems Standard gives definitions of data and memory that
apply to a wide variety of computers. These definitions give us a way
to talk about the common elements of data and memory while ignoring the
details of specific hardware. Similarly, ANS Forth programs that use
data and memory in ways that conform to these definitions can also
ignore hardware details. The following sections discuss the definitions
and describe how to write programs that are independent of the
data/memory peculiarities of different computers.
<P>



<hr>
<A name=E.2.2>
<H2>E.2.2 Definitions</H2>
</a>

Three terms defined by ANS Forth are address unit, cell, and character.
The address space of an ANS Forth system is divided into an array of
address units; an address unit is the smallest collection of bits that
can be addressed. In other words, an address unit is the number of bits
spanned by the addresses addr and addr+1. The most prevalent machines
use 8-bit address units. Such <B>byte addressed</B> machines include
the Intel 8086 and Motorola 68000 families. However, other address unit
sizes exist. There are machines that are bit addressed and machines
that are 4-bit nibble addressed. There are also machines with address
units larger than 8-bits. For example, several Forth-in-hardware
computers are cell addressed.

<P>

The cell is the fundamental data type of a Forth system. A cell can be
a single-cell integer or a memory address. Forth's parameter and return
stacks are stacks of cells. Forth-83 specifies that a cell is 16-bits.
In ANS Forth the size of a cell is an implementation-defined number of
address units. Thus, an ANS Forth implemented on a 16-bit
microprocessor could use a 16-bit cell and an implementation on a 32-bit
machine could use a 32-bit cell. Also 18-bit machines, 36-bit machines,
etc., could support ANS Forth systems with 18 or 36-bit cells
respectively. In all of these systems, 
<a href=dpans6.htm#6.1.1290>DUP</a> 
does the same thing: it
duplicates the top of the data stack. 
! (<a href=dpans6.htm#6.1.0010>store</a>) 
behaves consistently
too: given two cells on the data stack it stores the second cell in the
memory location designated by the top cell.

<P>

Similarly, the definition of a character has been generalized to be an
implementation-defined number of address units (but at least eight
bits). This removes the need for a Forth implementor to provide 8-bit
characters on processors where it is inappropriate. For example, on an
18-bit machine with a 9-bit address unit, a 9-bit character would be
most convenient. Since, by definition, you can't address anything
smaller than an address unit, a character must be at least as big as an
address unit. This will result in big characters on machines with large
address units. An example is a 16-bit cell addressed machine where a
16-bit character makes the most sense.

<P>


<hr>
<A name=E.2.3>
<H2>E.2.3 Addressing memory</H2>
</a>

ANS Forth eliminates many portability problems by using the above
definitions. One of the most common portability problems is addressing
successive cells in memory. Given the memory address of a cell, how do
you find the address of the next cell? In Forth-83 this is easy: 2 + .
This code assumes that memory is addressed in 8-bit units (bytes) and a
cell is 16-bits wide. On a byte-addressed machine with 32-bit cells the
code to find the next cell would be 4 + . The code would be 1+ on a
cell-addressed processor and 16+ on a bit-addressed processor with
16-bit cells. ANS Forth provides a next-cell operator named 
<a href=dpans6.htm#6.1.0880>CELL+</a> 
that
can be used in all of these cases. Given an address, CELL+ adjusts the
address by the size of a cell (measured in address units). A related
problem is that of addressing an array of cells in an arbitrary order.
A defining word to create an array of cells using Forth-83 would be:


<PRE>
	: ARRAY   CREATE  2* ALLOT  DOES> SWAP 2* + ;
</PRE>

<P>

Use of 
<a href=dpans6.htm#6.1.0320>2*</a> 
to scale the array index assumes byte addressing and 16-bit
cells again. As in the example above, different versions of the code
would be needed for different machines. ANS Forth provides a portable
scaling operator named 
<a href=dpans6.htm#6.1.0890>CELLS</a>. 
Given a number n, CELLS returns the
number of address units needed to hold n cells. A portable definition
of array is:

<PRE>
	: ARRAY   CREATE  CELLS ALLOT
	   DOES> SWAP CELLS + ;
</PRE>
<P>

There are also portability problems with addressing arrays of
characters. In Forth-83 (and in the most common ANS Forth
implementations), the size of a character will equal the size of an
address unit. Consequently addresses of successive characters in memory
can be found using 
<a href=dpans6.htm#6.1.0290>1+</a> 
and scaling indices into a character array is a
no-op (i.e., 1 *). However, there are cases where a character is larger
than an address unit. Examples include (1) systems with small address
units (e.g., bit- and nibble-addressed systems), and (2) systems with
large character sets (e.g., 16-bit characters on a byte-addressed
machine). 
<a href=dpans6.htm#6.1.0897>CHAR+</a> 
and 
<a href=dpans6.htm#6.1.0898>CHARS</a> 
operators, analogous to CELL+ and CELLS are
available to allow maximum portability.
<P>

ANS Forth generalizes the definition of some Forth words that operate on
chunks of memory to use address units. One example is 
<a href=dpans6.htm#6.1.0710>ALLOT</a>. By
prefixing ALLOT with the appropriate scaling operator (CELLS, CHARS,
etc.), space for any desired data structure can be allocated (see
definition of array above). For example:

<PRE>
	CREATE ABUFFER 5 CHARS ALLOT ( allot 5 character buffer)
</PRE>
<P>

The memory-block-move
word also uses address units:


<PRE>
	source destination 8 CELLS MOVE  (  move 8 cells)
</PRE>
<P>


<hr>
<A name=E.2.4>
<H2>E.2.4 Alignment problems</H2>
</a>

Not all addresses are created equal. Many processors have restrictions
on the addresses that can be used by memory access instructions. This
Standard does not require an implementor of an ANS Forth to make
alignment transparent; on the contrary, it requires (in 
<a href=dpans3.htm#3.3.3.1>Section 3.3.3.1</a>
Address alignment) that an ANS Forth program assume that character and
cell alignment may be required.

<P>

One of the most common problems caused by alignment restrictions is in
creating tables containing both characters and cells. When 
, (<a href=dpans6.htm#6.1.0150>comma</a>) or
<a href=dpans6.htm#6.1.0860>C,</a> 
is used to initialize a table, data is stored at the data-space
pointer. Consequently, it must be suitably aligned. For example, a
non-portable table definition would be:


<PRE>
	CREATE ATABLE   1 C,  X ,  2 C,  Y ,
</PRE>

<P>

On a machine that restricts 16-bit fetches to even addresses, 
<a href=dpans6.htm#6.1.1000>CREATE</a>
would leave the data space pointer at an even address, the 1 C, would
make the data space pointer odd, and , (comma) would violate the address
restriction by storing X at an odd address. A portable way to create
the table is:


<PRE>
	CREATE ATABLE   1 C,  ALIGN X ,  2 C,  ALIGN Y ,
</PRE>

<P>

<a href=dpans6.htm#6.1.0705>ALIGN</a> 
adjusts the data space pointer to the first aligned address
greater than or equal to its current address. An aligned address is
suitable for storing or fetching characters, cells, cell pairs, or
double-cell numbers.

<P>

After initializing the table, we would also like to read values from the
table. For example, assume we want to fetch the first cell, X, from the
table. ATABLE CHAR+ gives the address of the first thing after the
character. However this may not be the address of X since we aligned
the dictionary pointer between the C, and the ,. The portable way to
get the address of X is:


<PRE>
	ATABLE CHAR+ ALIGNED
</PRE>

<P>

<a href=dpans6.htm#6.1.0706>ALIGNED</a> 
adjusts the address on top of the stack to the first aligned
address greater than or equal to its current value.

<P>


<hr>
<A name=E.3>
<H1>E.3 Number representation</H1>
</a>

Different computers represent numbers in different ways. An awareness
of these differences can help a programmer avoid writing a program that
depends on a particular representation.

<P>


<hr>
<A name=E.3.1>
<H2>E.3.1 Big endian vs. little endian</H2>
</a>

The constituent bits of a number in memory are kept in different orders
on different machines. Some machines place the most-significant part of
a number at an address in memory with less-significant parts following
it at higher addresses. Other machines do the opposite the
least-significant part is stored at the lowest address. For example,
the following code for a 16-bit 8086 <B>little endian</B> Forth would
produce the answer 34 (hex):


<PRE>
	VARIABLE FOO   HEX 1234 FOO !   FOO C@
</PRE>
<P>

The same code on a 16-bit 68000 <B>big endian</B> Forth would produce
the answer 12 (hex). A portable program cannot exploit the
representation of a number in memory.

<P>

A related issue is the representation of cell pairs and double-cell
numbers in memory. When a cell pair is moved from the stack to memory
with 
<a href=dpans6.htm#6.1.0310>2!</a>, 
the cell that was on top of the stack is placed at the lower
memory address. It is useful and reasonable to manipulate the
individual cells when they are in memory.

<P>


<hr>
<A name=E.3.2>
<H2>E.3.2 ALU organization</H2>
</a>

Different computers use different bit patterns to represent integers.
Possibilities include binary representations (two's complement, one's
complement, sign magnitude, etc.) and decimal representations (BCD,
etc.). Each of these formats creates advantages and disadvantages in
the design of a computer's arithmetic logic unit (ALU). The most
commonly used representation, two's complement, is popular because of
the simplicity of its addition and subtraction algorithms.

<P>

Programmers who have grown up on two's complement machines tend to
become intimate with their representation of numbers and take some
properties of that representation for granted. For example, a trick to
find the remainder of a number divided by a power of two is to mask off
some bits with 
<a href=dpans6.htm#6.1.0720>AND</a>. 
A common application of this trick is to test a
number for oddness using 1 AND. However, this will not work on a one's
complement machine if the number is negative (a portable technique is 2
<a href=dpans6.htm#6.1.1890>MOD</a>).

<P>

The remainder of this section is a (non-exhaustive) list of things to
watch for when portability between machines with binary representations
other than two's complement is desired.

<P>

To convert a single-cell number to a double-cell number, ANS Forth
provides the operator 
<a href=dpans6.htm#6.1.2170>S>D</a>. 
To convert a double-cell number to
single-cell, Forth programmers have traditionally used 
<a href=dpans6.htm#6.1.1260>DROP</a>. 
However,
this trick doesn't work on sign-magnitude machines. For portability a
<a href=dpans8.htm#8.6.1.1140>D&gt;S</a> 
operator is available. Converting an unsigned single-cell number to
a double-cell number can be done portably by pushing a zero on the
stack.

<P>


<hr>
<A name=E.4>
<H1>E.4 Forth system implementation</H1>
</a>

During Forth's history, an amazing variety of implementation techniques
have been developed. The ANS Forth Standard encourages this diversity
and consequently restricts the assumptions a user can make about the
underlying implementation of an ANS Forth system. Users of a particular
Forth implementation frequently become accustomed to aspects of the
implementation and assume they are common to all Forths. This section
points out many of these incorrect assumptions.

<P>


<hr>
<A name=E.4.1>
<H2>E.4.1 Definitions</H2>
</a>

Traditionally, Forth definitions have consisted of the name of the Forth
word, a dictionary search link, data describing how to execute the
definition, and parameters describing the definition itself. These
components are called the name, link, code, and parameter fields. No
method for accessing these fields has been found that works across all
of the Forth implementations currently in use. Therefore, ANS Forth
severely restricts how the fields may be used. Specifically, a portable
ANS Forth program may not use the name, link, or code field in any way.
Use of the parameter field (renamed to data field for clarity) is
limited to the operations described below.

<P>

Only words defined with 
<a href=dpans6.htm#6.1.1000>CREATE</a> 
or with other defining words that call
CREATE have data fields. The other defining words in the Standard
(<a href=dpans6.htm#6.1.2410>VARIABLE</a>, 
<a href=dpans6.htm#6.1.0950>CONSTANT</a>, 
<a href=dpans6.htm#6.1.0450>:</a>, 
etc.) might not be implemented with CREATE.
Consequently, a Standard Program must assume that words defined by
VARIABLE, CONSTANT, : , etc., may have no data fields. There is no way
for a Standard Program to modify the value of a constant or to change
the meaning of a colon definition. The 
<a href=dpans6.htm#6.1.1250>DOES</a>> 
part of a defining word
operates on a data field. Since only CREATEd words have data fields,
DOES> can only be paired with CREATE or words that call CREATE.

<P>

In ANS Forth, 
<a href=dpans6.htm#6.1.1550>FIND</a>, 
<a href=dpans6.htm#6.1.2510>[']</a> and 
' (<a href=dpans6.htm#6.1.0070>tick</a>) 
return an unspecified entity called
an <B>execution token</B>. There are only a few things that may be done
with an execution token. The token may be passed to 
<a href=dpans6.htm#6.1.1370>EXECUTE</a> 
to execute
the word ticked or compiled into the current definition with 
<a href=dpans6.htm#6.2.0945>COMPILE,</a>.
The token can also be stored in a variable and used later. Finally, if
the word ticked was defined via CREATE, 
<a href=dpans6.htm#6.1.0550>>BODY</a> 
converts the execution
token into the word's data-field address.

<P>

One thing that definitely cannot be done with an execution token is use
<a href=dpans6.htm#6.1.0010>!</a> 
or 
<a href=dpans6.htm#6.1.0150>,</a> 
to store it into the object code of a Forth definition. This
technique is sometimes used in implementations where the object code is
a list of addresses (threaded code) and an execution token is also an
address. However, ANS Forth permits native code implementations where
this will not work.

<P>


<hr>
<A name=E.4.2>
<H2>E.4.2 Stacks</H2>
</a>

In some Forth implementations, it is possible to find the address of a
stack in memory and manipulate the stack as an array of cells. This
technique is not portable, however. On some systems, especially
Forth-in-hardware systems, the stacks might be in a part of memory that
can't be addressed by the program or might not be in memory at all.
Forth's parameter and return stacks must be treated as stacks.

<P>

A Standard Program may use the return stack directly only for
temporarily storing values. Every value examined or removed from the
return stack using 
<a href=dpans6.htm#6.1.2070>R@</a>, 
<a href=dpans6.htm#6.1.2060>R></a>, or 
<a href=dpans6.htm#6.2.0410>2R></a> 
must have been put on the stack
explicitly using 
<a href=dpans6.htm#6.1.0580>>R</a> or 
<a href=dpans6.htm#6.2.0340>2>R</a>. 
Even this must be done carefully since the
system may use the return stack to hold return addresses and
loop-control parameters. 
<a href=dpans3.htm#3.2.3.3>Section 3.2.3.3</a> Return stack of the Standard
has a list of restrictions.

<P>


<hr>
<A name=E.5>
<H1>E.5 ROMed application disciplines and conventions</H1>
</a>

When a Standard System provides a data space which is uniformly readable
and writeable we may term this environment <B>RAM-only</B>.

<P>

Programs designed for ROMed application must divide data space into at
least two parts: a writeable and readable uninitialized part, called
<B>RAM</B>, and a read-only initialized part, called <B>ROM</B>. A
third possibility, a writeable and readable initialized part, normally
called <B>initialized RAM</B>, is not addressed by this discipline. A
Standard Program must explicitly initialize the RAM data space as
needed.

<P>

The separation of data space into RAM and ROM is meaningful only during
the generation of the ROMed program. If the ROMed program is itself a
standard development system, it has the same taxonomy as an ordinary
RAM-only system.

<P>

The words affected by conversion from a RAM-only to a mixed RAM and ROM
environment are:

<p>
, (<a href=dpans6.htm#6.1.0150>comma</a>)  
<a href=dpans6.htm#6.1.0705>ALIGN</a>  
<a href=dpans6.htm#6.1.0706>ALIGNED</a>  
<a href=dpans6.htm#6.1.0710>ALLOT</a>  
<a href=dpans6.htm#6.1.0860>C,</a>  
<a href=dpans6.htm#6.1.1000>CREATE</a>  
<a href=dpans6.htm#6.1.1650>HERE</a>  
<a href=dpans6.htm#6.2.2395>UNUSED</a>
<P>

(<a href=dpans6.htm#6.1.2410>VARIABLE</a> always
accesses the RAM data space.)

<P>

With the exception of , (comma) and C,
these words are meaningful in both RAM
and ROM data space.

<P>

To select the data space, these words could be preceded by selectors RAM
and ROM. For example:


<PRE>
	ROM  CREATE ONES  32 ALLOT  ONES 32 1 FILL  RAM
</PRE>

<P>

would create a table of ones in the ROM data space. The storage of data
into RAM data space when generating a program for ROM would be an
ambiguous condition.

<P>

A straightforward implementation of these selectors would maintain
separate address counters for each space. A counter value would be
returned by HERE and altered by , (comma), C,, ALIGN, and ALLOT, with
RAM and ROM simply selecting the appropriate address counter. This
technique could be extended to additional partitions of the data space.

<P>


<hr>
<A name=E.6>
<H1>E.6 Summary</H1>
</a>

The ANS Forth Standard cannot and should not force anyone to write a
portable program. In situations where performance is paramount, the
programmer is encouraged to use every trick in the book. On the other
hand, if portability to a wide variety of systems is needed, ANS Forth
provides the tools to accomplish this. There is probably no such thing
as a completely portable program. A programmer, using this guide,
should intelligently weigh the tradeoffs of providing portability to
specific machines. For example, machines that use sign-magnitude
numbers are rare and probably don't deserve much thought. But, systems
with different cell sizes will certainly be encountered and should be
provided for. In general, making a program portable clarifies both the
programmer's thinking process and the final program.

<P>


<hr>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents 
<BR>
<A href=dpansf.htm><IMG   src="right.gif" ></A>
Next Section
<P>
</BODY>
</HTML>

dpansf.htm/     845512500   500   0     100644  38915     `
<HTML><HEAD>
<TITLE>DPANS94</TITLE>
</HEAD>

<BODY>
<table width=100%>
<tr>
<td align=left>
<a href=dpanse.html><img src=left.gif
 width=26 height=26 align=ALIGN border=0></a>
</td>
<td align=right>
<a href=dpans.htm#toc><img src=up.gif 
 width=26 height=26 align=ALIGN border=0></a>
<a name=F.>Table of Contents</a>
</td>
</tr>
</table>
<p>
<hr size=4>

<H1>F. Alphabetic list of words (informative
annex)</H1>

In the following list, the last, four-digit, part of the reference number
establishes a sequence corresponding to the alphabetic ordering of all
standard words.  The first two or three parts indicate the word set and
glossary section in which the word is defined.


<PRE>
          <A href=dpans6.htm#6.1.0010>.6.1.0010</A>   !           <B>store</B>                 CORE
          <A href=dpans6.htm#6.1.0030>.6.1.0030</A>   #           <B>number-sign</B>           CORE
          <A href=dpans6.htm#6.1.0040>.6.1.0040</A>   #>          <B>number-sign-greater</B>   CORE
          <A href=dpans6.htm#6.1.0050>.6.1.0050</A>   #S          <B>number-sign-s</B>         CORE
          <A href=dpans6.htm#6.2.0060>.6.2.0060</A>   #TIB        <B>number-t-i-b</B>          CORE EXT
          <A href=dpans6.htm#6.1.0070>.6.1.0070</A>   '           <B>tick</B>                  CORE
          <A href=dpans6.htm#6.1.0080>.6.1.0080</A>   (           <B>paren</B>                 CORE
        <A href=dpans11.htm#11.6.1.0080>11.6.1.0080</A>   (           <B>paren</B>                 FILE
        <A href=dpans13.htm#13.6.1.0086>13.6.1.0086</A>   (LOCAL)     <B>paren-local-paren</B>     LOCAL
          <A href=dpans6.htm#6.1.0090>.6.1.0090</A>   *           <B>star</B>                  CORE
          <A href=dpans6.htm#6.1.0100>.6.1.0100</A>   */          <B>star-slash</B>            CORE
          <A href=dpans6.htm#6.1.0110>.6.1.0110</A>   */MOD       <B>star-slash-mod</B>        CORE
          <A href=dpans6.htm#6.1.0120>.6.1.0120</A>   +           <B>plus</B>                  CORE
          <A href=dpans6.htm#6.1.0130>.6.1.0130</A>   +!          <B>plus-store</B>            CORE
          <A href=dpans6.htm#6.1.0140>.6.1.0140</A>   +LOOP       <B>plus-loop</B>             CORE
          <A href=dpans6.htm#6.1.0150>.6.1.0150</A>   ,           <B>comma</B>                 CORE
          <A href=dpans6.htm#6.1.0160>.6.1.0160</A>   -           <B>minus</B>                 CORE
        <A href=dpans17.htm#17.6.1.0170>17.6.1.0170</A>   -TRAILING   <B>dash-trailing</B>         STRING
          <A href=dpans6.htm#6.1.0180>.6.1.0180</A>   .           <B>dot</B>                   CORE
          <A href=dpans6.htm#6.1.0190>.6.1.0190</A>   ."          <B>dot-quote</B>             CORE
          <A href=dpans6.htm#6.2.0200>.6.2.0200</A>   .(          <B>dot-paren</B>             CORE EXT
          <A href=dpans6.htm#6.2.0210>.6.2.0210</A>   .R          <B>dot-r</B>                 CORE EXT
        <A href=dpans15.htm#15.6.1.0220>15.6.1.0220</A>   .S          <B>dot-s</B>                 TOOLS
          <A href=dpans6.htm#6.1.0230>.6.1.0230</A>   /           <B>slash</B>                 CORE
          <A href=dpans6.htm#6.1.0240>.6.1.0240</A>   /MOD        <B>slash-mod</B>             CORE
        <A href=dpans17.htm#17.6.1.0245>17.6.1.0245</A>   /STRING     <B>slash-string</B>          STRING
          <A href=dpans6.htm#6.1.0250>.6.1.0250</A>   0<          <B>zero-less</B>             CORE
          <A href=dpans6.htm#6.2.0260>.6.2.0260</A>   0<&gt;         <B>zero-not-equals</B>       CORE EXT
          <A href=dpans6.htm#6.1.0270>.6.1.0270</A>   0=          <B>zero-equals</B>           CORE
          <A href=dpans6.htm#6.2.0280>.6.2.0280</A>   0&gt;          <B>zero-greater</B>          CORE EXT
          <A href=dpans6.htm#6.1.0290>.6.1.0290</A>   1+          <B>one-plus</B>              CORE
          <A href=dpans6.htm#6.1.0300>.6.1.0300</A>   1-          <B>one-minus</B>             CORE
          <A href=dpans6.htm#6.1.0310>.6.1.0310</A>   2!          <B>two-store</B>             CORE
          <A href=dpans6.htm#6.1.0320>.6.1.0320</A>   2*          <B>two-star</B>              CORE
          <A href=dpans6.htm#6.1.0330>.6.1.0330</A>   2/          <B>two-slash</B>             CORE
          <A href=dpans6.htm#6.2.0340>.6.2.0340</A>   2&gt;R         <B>two-to-r</B>              CORE EXT
          <A href=dpans6.htm#6.1.0350>.6.1.0350</A>   2@          <B>two-fetch</B>             CORE
         <A href=dpans8.htm#8.6.1.0360>8.6.1.0360</A>   2CONSTANT   <B>two-constant</B>          DOUBLE
          <A href=dpans6.htm#6.1.0370>.6.1.0370</A>   2DROP       <B>two-drop</B>              CORE
          <A href=dpans6.htm#6.1.0380>.6.1.0380</A>   2DUP        <B>two-dupe</B>              CORE
         <A href=dpans8.htm#8.6.1.0390>8.6.1.0390</A>   2LITERAL    <B>two-literal</B>           DOUBLE
          <A href=dpans6.htm#6.1.0400>.6.1.0400</A>   2OVER       <B>two-over</B>              CORE
          <A href=dpans6.htm#6.2.0410>.6.2.0410</A>   2R>         <B>two-r-from</B>            CORE EXT
          <A href=dpans6.htm#6.2.0415>.6.2.0415</A>   2R@         <B>two-r-fetch</B>           CORE EXT
         <A href=dpans8.htm#8.6.2.0420>8.6.2.0420</A>   2ROT        <B>two-rote</B>              DOUBLE EXT
          <A href=dpans6.htm#6.1.0430>.6.1.0430</A>   2SWAP       <B>two-swap</B>              CORE
         <A href=dpans8.htm#8.6.1.0440>8.6.1.0440</A>   2VARIABLE   <B>two-variable</B>          DOUBLE
          <A href=dpans6.htm#6.1.0450>.6.1.0450</A>   :           <B>colon</B>                 CORE
          <A href=dpans6.htm#6.2.0455>.6.2.0455</A>   :NONAME     <B>colon-no-name</B>         CORE EXT
          <A href=dpans6.htm#6.1.0460>.6.1.0460</A>   ;           <B>semicolon</B>             CORE
        <A href=dpans15.htm#15.6.2.0470>15.6.2.0470</A>   ;CODE       <B>semicolon-code</B>        TOOLS EXT
          <A href=dpans6.htm#6.1.0480>.6.1.0480</A>   &lt;           <B>less-than</B>             CORE
          <A href=dpans6.htm#6.1.0490>.6.1.0490</A>   &lt;#          <B>less-number-sign</B>      CORE
          <A href=dpans6.htm#6.2.0500>.6.2.0500</A>   &lt;>          <B>not-equals</B>            CORE EXT
          <A href=dpans6.htm#6.1.0530>.6.1.0530</A>   =           <B>equals</B>                CORE
          <A href=dpans6.htm#6.1.0540>.6.1.0540</A>   >           <B>greater-than</B>          CORE
          <A href=dpans6.htm#6.1.0550>.6.1.0550</A>   >BODY       <B>to-body</B>               CORE
        <A href=dpans12.htm#12.6.1.0558>12.6.1.0558</A>   >FLOAT      <B>to-float</B>              FLOATING
          <A href=dpans6.htm#6.1.0560>.6.1.0560</A>   >IN         <B>to-in</B>                 CORE
          <A href=dpans6.htm#6.1.0570>.6.1.0570</A>   >NUMBER     <B>to-number</B>             CORE
          <A href=dpans6.htm#6.1.0580>.6.1.0580</A>   >R          <B>to-r</B>                  CORE
        <A href=dpans15.htm#15.6.1.0600>15.6.1.0600</A>   ?           <B>question</B>              TOOLS
          <A href=dpans6.htm#6.2.0620>.6.2.0620</A>   ?DO         <B>question-do</B>           CORE EXT
          <A href=dpans6.htm#6.1.0630>.6.1.0630</A>   ?DUP        <B>question-dupe</B>         CORE
          <A href=dpans6.htm#6.1.0650>.6.1.0650</A>   @           <B>fetch</B>                 CORE
          <A href=dpans6.htm#6.1.0670>.6.1.0670</A>   ABORT                             CORE
         <A href=dpans9.htm#9.6.2.0670>9.6.2.0670</A>   ABORT                             EXCEPTION EXT
          <A href=dpans6.htm#6.1.0680>.6.1.0680</A>   ABORT"      <B>abort-quote</B>           CORE
         <A href=dpans9.htm#9.6.2.0680>9.6.2.0680</A>   ABORT"      <B>abort-quote</B>           EXCEPTION EXT
          <A href=dpans6.htm#6.1.0690>.6.1.0690</A>   ABS         <B>abs</B>                   CORE
          <A href=dpans6.htm#6.1.0695>.6.1.0695</A>   ACCEPT                            CORE
          <A href=dpans6.htm#6.2.0700>.6.2.0700</A>   AGAIN                             CORE EXT
        <A href=dpans15.htm#15.6.2.0702>15.6.2.0702</A>   AHEAD                             TOOLS EXT
          <A href=dpans6.htm#6.1.0705>.6.1.0705</A>   ALIGN                             CORE
          <A href=dpans6.htm#6.1.0706>.6.1.0706</A>   ALIGNED                           CORE
        <A href=dpans14.htm#14.6.1.0707>14.6.1.0707</A>   ALLOCATE                          MEMORY
          <A href=dpans6.htm#6.1.0710>.6.1.0710</A>   ALLOT                             CORE
        <A href=dpans16.htm#16.6.2.0715>16.6.2.0715</A>   ALSO                              SEARCH EXT
          <A href=dpans6.htm#6.1.0720>.6.1.0720</A>   AND                               CORE
        <A href=dpans15.htm#15.6.2.0740>15.6.2.0740</A>   ASSEMBLER                         TOOLS EXT
        <A href=dpans10.htm#10.6.1.0742>10.6.1.0742</A>   AT-XY       <B>at-x-y</B>                FACILITY
          <A href=dpans6.htm#6.1.0750>.6.1.0750</A>   BASE                              CORE
          <A href=dpans6.htm#6.1.0760>.6.1.0760</A>   BEGIN                             CORE
        <A href=dpans11.htm#11.6.1.0765>11.6.1.0765</A>   BIN                               FILE
          <A href=dpans6.htm#6.1.0770>.6.1.0770</A>   BL          <B>b-l</B>                   CORE
        <A href=dpans17.htm#17.6.1.0780>17.6.1.0780</A>   BLANK                             STRING
         <A href=dpans7.htm#7.6.1.0790>7.6.1.0790</A>   BLK         <B>b-l-k</B>                 BLOCK
         <A href=dpans7.htm#7.6.1.0800>7.6.1.0800</A>   BLOCK                             BLOCK
         <A href=dpans7.htm#7.6.1.0820>7.6.1.0820</A>   BUFFER                            BLOCK
        <A href=dpans15.htm#15.6.2.0830>15.6.2.0830</A>   BYE                               TOOLS EXT
          <A href=dpans6.htm#6.1.0850>.6.1.0850</A>   C!          <B>c-store</B>               CORE
          <A href=dpans6.htm#6.2.0855>.6.2.0855</A>   C"          <B>c-quote</B>               CORE EXT
          <A href=dpans6.htm#6.1.0860>.6.1.0860</A>   C,          <B>c-comma</B>               CORE
          <A href=dpans6.htm#6.1.0870>.6.1.0870</A>   C@          <B>c-fetch</B>               CORE
          <A href=dpans6.htm#6.2.0873>.6.2.0873</A>   CASE                              CORE EXT
         <A href=dpans9.htm#9.6.1.0875>9.6.1.0875</A>   CATCH                             EXCEPTION
          <A href=dpans6.htm#6.1.0880>.6.1.0880</A>   CELL+       <B>cell-plus</B>             CORE
          <A href=dpans6.htm#6.1.0890>.6.1.0890</A>   CELLS                             CORE
          <A href=dpans6.htm#6.1.0895>.6.1.0895</A>   CHAR        <B>char</B>                  CORE
          <A href=dpans6.htm#6.1.0897>.6.1.0897</A>   CHAR+       <B>char-plus</B>             CORE
          <A href=dpans6.htm#6.1.0898>.6.1.0898</A>   CHARS       <B>chars</B>                 CORE
        <A href=dpans11.htm#11.6.1.0900>11.6.1.0900</A>   CLOSE-FILE                        FILE
        <A href=dpans17.htm#17.6.1.0910>17.6.1.0910</A>   CMOVE       <B>c-move</B>                STRING
        <A href=dpans17.htm#17.6.1.0920>17.6.1.0920</A>   CMOVE>      <B>c-move-up</B>             STRING
        <A href=dpans15.htm#15.6.2.0930>15.6.2.0930</A>   CODE                              TOOLS EXT
        <A href=dpans17.htm#17.6.1.0935>17.6.1.0935</A>   COMPARE                           STRING
          <A href=dpans6.htm#6.2.0945>.6.2.0945</A>   COMPILE,    <B>compile-comma</B>         CORE EXT
          <A href=dpans6.htm#6.1.0950>.6.1.0950</A>   CONSTANT                          CORE
          <A href=dpans6.htm#6.2.0970>.6.2.0970</A>   CONVERT                           CORE EXT
          <A href=dpans6.htm#6.1.0980>.6.1.0980</A>   COUNT                             CORE
          <A href=dpans6.htm#6.1.0990>.6.1.0990</A>   CR          <B>c-r</B>                   CORE
          <A href=dpans6.htm#6.1.1000>.6.1.1000</A>   CREATE                            CORE
        <A href=dpans11.htm#11.6.1.1010>11.6.1.1010</A>   CREATE-FILE                       FILE
        <A href=dpans15.htm#15.6.2.1015>15.6.2.1015</A>   CS-PICK     <B>c-s-pick</B>              TOOLS EXT
        <A href=dpans15.htm#15.6.2.1020>15.6.2.1020</A>   CS-ROLL     <B>c-s-roll</B>              TOOLS EXT
         <A href=dpans8.htm#8.6.1.1040>8.6.1.1040</A>   D+          <B>d-plus</B>                DOUBLE
         <A href=dpans8.htm#8.6.1.1050>8.6.1.1050</A>   D-          <B>d-minus</B>               DOUBLE
         <A href=dpans8.htm#8.6.1.1060>8.6.1.1060</A>   D.          <B>d-dot</B>                 DOUBLE
         <A href=dpans8.htm#8.6.1.1070>8.6.1.1070</A>   D.R         <B>d-dot-r</B>               DOUBLE
         <A href=dpans8.htm#8.6.1.1075>8.6.1.1075</A>   D0<         <B>d-zero-less</B>           DOUBLE
         <A href=dpans8.htm#8.6.1.1080>8.6.1.1080</A>   D0=         <B>d-zero-equals</B>         DOUBLE
         <A href=dpans8.htm#8.6.1.1090>8.6.1.1090</A>   D2*         <B>d-two-star</B>            DOUBLE
         <A href=dpans8.htm#8.6.1.1100>8.6.1.1100</A>   D2/         <B>d-two-slash</B>           DOUBLE
         <A href=dpans8.htm#8.6.1.1110>8.6.1.1110</A>   D<          <B>d-less-than</B>           DOUBLE
         <A href=dpans8.htm#8.6.1.1120>8.6.1.1120</A>   D=          <B>d-equals</B>              DOUBLE
        <A href=dpans12.htm#12.6.1.1130>12.6.1.1130</A>   D>F         <B>d-to-f</B>                FLOATING
         <A href=dpans8.htm#8.6.1.1140>8.6.1.1140</A>   D>S         <B>d-to-s</B>                DOUBLE
         <A href=dpans8.htm#8.6.1.1160>8.6.1.1160</A>   DABS        <B>d-abs</B>                 DOUBLE
          <A href=dpans6.htm#6.1.1170>.6.1.1170</A>   DECIMAL                           CORE
        <A href=dpans16.htm#16.6.1.1180>16.6.1.1180</A>   DEFINITIONS                       SEARCH
        <A href=dpans11.htm#11.6.1.1190>11.6.1.1190</A>   DELETE-FILE                       FILE
          <A href=dpans6.htm#6.1.1200>.6.1.1200</A>   DEPTH                             CORE
        <A href=dpans12.htm#12.6.2.1203>12.6.2.1203</A>   DF!         <B>d-f-store</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.1204>12.6.2.1204</A>   DF@         <B>d-f-fetch</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.1205>12.6.2.1205</A>   DFALIGN     <B>d-f-align</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.1207>12.6.2.1207</A>   DFALIGNED   <B>d-f-aligned</B>           FLOATING EXT
        <A href=dpans12.htm#12.6.2.1208>12.6.2.1208</A>   DFLOAT+     <B>d-float-plus</B>          FLOATING EXT
        <A href=dpans12.htm#12.6.2.1209>12.6.2.1209</A>   DFLOATS     <B>d-floats</B>              FLOATING EXT
         <A href=dpans8.htm#8.6.1.1210>8.6.1.1210</A>   DMAX        <B>d-max</B>                 DOUBLE
         <A href=dpans8.htm#8.6.1.1220>8.6.1.1220</A>   DMIN        <B>d-min</B>                 DOUBLE
         <A href=dpans8.htm#8.6.1.1230>8.6.1.1230</A>   DNEGATE     <B>d-negate</B>              DOUBLE
          <A href=dpans6.htm#6.1.1240>.6.1.1240</A>   DO                                CORE
          <A href=dpans6.htm#6.1.1250>.6.1.1250</A>   DOES>       <B>does</B>                  CORE
          <A href=dpans6.htm#6.1.1260>.6.1.1260</A>   DROP                              CORE
         <A href=dpans8.htm#8.6.2.1270>8.6.2.1270</A>   DU<         <B>d-u-less</B>              DOUBLE EXT
        <A href=dpans15.htm#15.6.1.1280>15.6.1.1280</A>   DUMP                              TOOLS
          <A href=dpans6.htm#6.1.1290>.6.1.1290</A>   DUP         <B>dupe</B>                  CORE
        <A href=dpans15.htm#15.6.2.1300>15.6.2.1300</A>   EDITOR                            TOOLS EXT
        <A href=dpans10.htm#10.6.2.1305>10.6.2.1305</A>   EKEY        <B>e-key</B>                 FACILITY EXT
        <A href=dpans10.htm#10.6.2.1306>10.6.2.1306</A>   EKEY>CHAR   <B>e-key-to-char</B>         FACILITY EXT
        <A href=dpans10.htm#10.6.2.1307>10.6.2.1307</A>   EKEY?       <B>e-key-question</B>        FACILITY EXT
          <A href=dpans6.htm#6.1.1310>.6.1.1310</A>   ELSE                              CORE
          <A href=dpans6.htm#6.1.1320>.6.1.1320</A>   EMIT                              CORE
        <A href=dpans10.htm#10.6.2.1325>10.6.2.1325</A>   EMIT?       <B>emit-question</B>         FACILITY EXT
         <A href=dpans7.htm#7.6.2.1330>7.6.2.1330</A>   EMPTY-BUFFERS                     BLOCK EXT
          <A href=dpans6.htm#6.2.1342>.6.2.1342</A>   ENDCASE     <B>end-case</B>              CORE EXT
          <A href=dpans6.htm#6.2.1343>.6.2.1343</A>   ENDOF       <B>end-of</B>                CORE EXT
          <A href=dpans6.htm#6.1.1345>.6.1.1345</A>   ENVIRONMENT?<B>environment-query</B>     CORE
          <A href=dpans6.htm#6.2.1350>.6.2.1350</A>   ERASE                             CORE EXT
          <A href=dpans6.htm#6.1.1360>.6.1.1360</A>   EVALUATE                          CORE
         <A href=dpans7.htm#7.6.1.1360>7.6.1.1360</A>   EVALUATE                          BLOCK
          <A href=dpans6.htm#6.1.1370>.6.1.1370</A>   EXECUTE                           CORE
          <A href=dpans6.htm#6.1.1380>.6.1.1380</A>   EXIT                              CORE
          <A href=dpans6.htm#6.2.1390>.6.2.1390</A>   EXPECT                            CORE EXT
        <A href=dpans12.htm#12.6.1.1400>12.6.1.1400</A>   F!          <B>f-store</B>               FLOATING
        <A href=dpans12.htm#12.6.1.1410>12.6.1.1410</A>   F*          <B>f-star</B>                FLOATING
        <A href=dpans12.htm#12.6.2.1415>12.6.2.1415</A>   F**         <B>f-star-star</B>           FLOATING EXT
        <A href=dpans12.htm#12.6.1.1420>12.6.1.1420</A>   F+          <B>f-plus</B>                FLOATING
        <A href=dpans12.htm#12.6.1.1425>12.6.1.1425</A>   F-          <B>f-minus</B>               FLOATING
        <A href=dpans12.htm#12.6.2.1427>12.6.2.1427</A>   F.          <B>f-dot</B>                 FLOATING EXT
        <A href=dpans12.htm#12.6.1.1430>12.6.1.1430</A>   F/          <B>f-slash</B>               FLOATING
        <A href=dpans12.htm#12.6.1.1440>12.6.1.1440</A>   F0<         <B>f-zero-less-than</B>      FLOATING
        <A href=dpans12.htm#12.6.1.1450>12.6.1.1450</A>   F0=         <B>f-zero-equals</B>         FLOATING
        <A href=dpans12.htm#12.6.1.1460>12.6.1.1460</A>   F<          <B>f-less-than</B>           FLOATING
        <A href=dpans12.htm#12.6.1.1470>12.6.1.1470</A>   F>D         <B>f-to-d</B>                FLOATING
        <A href=dpans12.htm#12.6.1.1472>12.6.1.1472</A>   F@          <B>f-fetch</B>               FLOATING
        <A href=dpans12.htm#12.6.2.1474>12.6.2.1474</A>   FABS        <B>f-abs</B>                 FLOATING EXT
        <A href=dpans12.htm#12.6.2.1476>12.6.2.1476</A>   FACOS       <B>f-a-cos</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.2.1477>12.6.2.1477</A>   FACOSH      <B>f-a-cosh</B>              FLOATING EXT
        <A href=dpans12.htm#12.6.1.1479>12.6.1.1479</A>   FALIGN      <B>f-align</B>               FLOATING
        <A href=dpans12.htm#12.6.1.1483>12.6.1.1483</A>   FALIGNED    <B>f-aligned</B>             FLOATING
        <A href=dpans12.htm#12.6.2.1484>12.6.2.1484</A>   FALOG       <B>f-a-log</B>               FLOATING EXT
          <A href=dpans6.htm#6.2.1485>.6.2.1485</A>   FALSE                             CORE EXT
        <A href=dpans12.htm#12.6.2.1486>12.6.2.1486</A>   FASIN       <B>f-a-sine</B>              FLOATING EXT
        <A href=dpans12.htm#12.6.2.1487>12.6.2.1487</A>   FASINH      <B>f-a-cinch</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.1488>12.6.2.1488</A>   FATAN       <B>f-a-tan</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.2.1489>12.6.2.1489</A>   FATAN2      <B>f-a-tan-two</B>           FLOATING EXT
        <A href=dpans12.htm#12.6.2.1491>12.6.2.1491</A>   FATANH      <B>f-a-tan-h</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.1.1492>12.6.1.1492</A>   FCONSTANT   <B>f-constant</B>            FLOATING
        <A href=dpans12.htm#12.6.2.1493>12.6.2.1493</A>   FCOS        <B>f-cos</B>                 FLOATING EXT
        <A href=dpans12.htm#12.6.2.1494>12.6.2.1494</A>   FCOSH       <B>f-cosh</B>                FLOATING EXT
        <A href=dpans12.htm#12.6.1.1497>12.6.1.1497</A>   FDEPTH      <B>f-depth</B>               FLOATING
        <A href=dpans12.htm#12.6.1.1500>12.6.1.1500</A>   FDROP       <B>f-drop</B>                FLOATING
        <A href=dpans12.htm#12.6.1.1510>12.6.1.1510</A>   FDUP        <B>f-dupe</B>                FLOATING
        <A href=dpans12.htm#12.6.2.1513>12.6.2.1513</A>   FE.         <B>f-e-dot</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.2.1515>12.6.2.1515</A>   FEXP        <B>f-e-x-p</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.2.1516>12.6.2.1516</A>   FEXPM1      <B>f-e-x-p-m-one</B>         FLOATING EXT
        <A href=dpans11.htm#11.6.1.1520>11.6.1.1520</A>   FILE-POSITION                     FILE
        <A href=dpans11.htm#11.6.1.1522>11.6.1.1522</A>   FILE-SIZE                         FILE
        <A href=dpans11.htm#11.6.2.1524>11.6.2.1524</A>   FILE-STATUS                       FILE EXT
          <A href=dpans6.htm#6.1.1540>.6.1.1540</A>   FILL                              CORE
          <A href=dpans6.htm#6.1.1550>.6.1.1550</A>   FIND                              CORE
        <A href=dpans16.htm#16.6.1.1550>16.6.1.1550</A>   FIND                              SEARCH
        <A href=dpans12.htm#12.6.1.1552>12.6.1.1552</A>   FLITERAL    <B>f-literal</B>             FLOATING
        <A href=dpans12.htm#12.6.2.1553>12.6.2.1553</A>   FLN         <B>f-l-n</B>                 FLOATING EXT
        <A href=dpans12.htm#12.6.2.1554>12.6.2.1554</A>   FLNP1       <B>f-l-n-p-one</B>           FLOATING EXT
        <A href=dpans12.htm#12.6.1.1555>12.6.1.1555</A>   FLOAT+      <B>float-plus</B>            FLOATING
        <A href=dpans12.htm#12.6.1.1556>12.6.1.1556</A>   FLOATS                            FLOATING
        <A href=dpans12.htm#12.6.2.1557>12.6.2.1557</A>   FLOG        <B>f-log</B>                 FLOATING EXT
        <A href=dpans12.htm#12.6.1.1558>12.6.1.1558</A>   FLOOR                             FLOATING
         <A href=dpans7.htm#7.6.1.1559>7.6.1.1559</A>   FLUSH                             BLOCK
        <A href=dpans11.htm#11.6.2.1560>11.6.2.1560</A>   FLUSH-FILE                        FILE EXT
          <A href=dpans6.htm#6.1.1561>.6.1.1561</A>   FM/MOD      <B>f-m-slash-mod</B>         CORE
        <A href=dpans12.htm#12.6.1.1562>12.6.1.1562</A>   FMAX        <B>f-max</B>                 FLOATING
        <A href=dpans12.htm#12.6.1.1565>12.6.1.1565</A>   FMIN        <B>f-min</B>                 FLOATING
        <A href=dpans12.htm#12.6.1.1567>12.6.1.1567</A>   FNEGATE     <B>f-negate</B>              FLOATING
        <A href=dpans15.htm#15.6.2.1580>15.6.2.1580</A>   FORGET                            TOOLS EXT
        <A href=dpans16.htm#16.6.2.1590>16.6.2.1590</A>   FORTH                             SEARCH EXT
        <A href=dpans16.htm#16.6.1.1595>16.6.1.1595</A>   FORTH-WORDLIST                    SEARCH
        <A href=dpans12.htm#12.6.1.1600>12.6.1.1600</A>   FOVER       <B>f-over</B>                FLOATING
        <A href=dpans14.htm#14.6.1.1605>14.6.1.1605</A>   FREE                              MEMORY
        <A href=dpans12.htm#12.6.1.1610>12.6.1.1610</A>   FROT        <B>f-rote</B>                FLOATING
        <A href=dpans12.htm#12.6.1.1612>12.6.1.1612</A>   FROUND      <B>f-round</B>               FLOATING
        <A href=dpans12.htm#12.6.2.1613>12.6.2.1613</A>   FS.         <B>f-s-dot</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.2.1614>12.6.2.1614</A>   FSIN        <B>f-sine</B>                FLOATING EXT
        <A href=dpans12.htm#12.6.2.1616>12.6.2.1616</A>   FSINCOS     <B>f-sine-cos</B>            FLOATING EXT
        <A href=dpans12.htm#12.6.2.1617>12.6.2.1617</A>   FSINH       <B>f-cinch</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.2.1618>12.6.2.1618</A>   FSQRT       <B>f-square-root</B>         FLOATING EXT
        <A href=dpans12.htm#12.6.1.1620>12.6.1.1620</A>   FSWAP       <B>f-swap</B>                FLOATING
        <A href=dpans12.htm#12.6.2.1625>12.6.2.1625</A>   FTAN        <B>f-tan</B>                 FLOATING EXT
        <A href=dpans12.htm#12.6.2.1626>12.6.2.1626</A>   FTANH       <B>f-tan-h</B>               FLOATING EXT
        <A href=dpans12.htm#12.6.1.1630>12.6.1.1630</A>   FVARIABLE   <B>f-variable</B>            FLOATING
        <A href=dpans12.htm#12.6.2.1640>12.6.2.1640</A>   F~          <B>f-proximate</B>           FLOATING EXT
        <A href=dpans16.htm#16.6.1.1643>16.6.1.1643</A>   GET-CURRENT                       SEARCH
        <A href=dpans16.htm#16.6.1.1647>16.6.1.1647</A>   GET-ORDER                         SEARCH
          <A href=dpans6.htm#6.1.1650>.6.1.1650</A>   HERE                              CORE
          <A href=dpans6.htm#6.2.1660>.6.2.1660</A>   HEX                               CORE EXT
          <A href=dpans6.htm#6.1.1670>.6.1.1670</A>   HOLD                              CORE
          <A href=dpans6.htm#6.1.1680>.6.1.1680</A>   I                                 CORE
          <A href=dpans6.htm#6.1.1700>.6.1.1700</A>   IF                                CORE
          <A href=dpans6.htm#6.1.1710>.6.1.1710</A>   IMMEDIATE                         CORE
        <A href=dpans11.htm#11.6.1.1717>11.6.1.1717</A>   INCLUDE-FILE                      FILE
        <A href=dpans11.htm#11.6.1.1718>11.6.1.1718</A>   INCLUDED                          FILE
          <A href=dpans6.htm#6.1.1720>.6.1.1720</A>   INVERT                            CORE
          <A href=dpans6.htm#6.1.1730>.6.1.1730</A>   J                                 CORE
          <A href=dpans6.htm#6.1.1750>.6.1.1750</A>   KEY                               CORE
        <A href=dpans10.htm#10.6.1.1755>10.6.1.1755</A>   KEY?        <B>key-question</B>          FACILITY
          <A href=dpans6.htm#6.1.1760>.6.1.1760</A>   LEAVE                             CORE
         <A href=dpans7.htm#7.6.2.1770>7.6.2.1770</A>   LIST                              BLOCK EXT
          <A href=dpans6.htm#6.1.1780>.6.1.1780</A>   LITERAL                           CORE
         <A href=dpans7.htm#7.6.1.1790>7.6.1.1790</A>   LOAD                              BLOCK
        <A href=dpans13.htm#13.6.2.1795>13.6.2.1795</A>   LOCALS|     <B>locals-bar</B>            LOCAL EXT
          <A href=dpans6.htm#6.1.1800>.6.1.1800</A>   LOOP                              CORE
          <A href=dpans6.htm#6.1.1805>.6.1.1805</A>   LSHIFT      <B>l-shift</B>               CORE
          <A href=dpans6.htm#6.1.1810>.6.1.1810</A>   M*          <B>m-star</B>                CORE
         <A href=dpans8.htm#8.6.1.1820>8.6.1.1820</A>   M*/         <B>m-star-slash</B>          DOUBLE
         <A href=dpans8.htm#8.6.1.1830>8.6.1.1830</A>   M+          <B>m-plus</B>                DOUBLE
          <A href=dpans6.htm#6.2.1850>.6.2.1850</A>   MARKER                            CORE EXT
          <A href=dpans6.htm#6.1.1870>.6.1.1870</A>   MAX                               CORE
          <A href=dpans6.htm#6.1.1880>.6.1.1880</A>   MIN                               CORE
          <A href=dpans6.htm#6.1.1890>.6.1.1890</A>   MOD                               CORE
          <A href=dpans6.htm#6.1.1900>.6.1.1900</A>   MOVE                              CORE
        <A href=dpans10.htm#10.6.2.1905>10.6.2.1905</A>   MS                                FACILITY EXT
          <A href=dpans6.htm#6.1.1910>.6.1.1910</A>   NEGATE                            CORE
          <A href=dpans6.htm#6.2.1930>.6.2.1930</A>   NIP                               CORE EXT
          <A href=dpans6.htm#6.2.1950>.6.2.1950</A>   OF                                CORE EXT
        <A href=dpans16.htm#16.6.2.1965>16.6.2.1965</A>   ONLY                              SEARCH EXT
        <A href=dpans11.htm#11.6.1.1970>11.6.1.1970</A>   OPEN-FILE                         FILE
          <A href=dpans6.htm#6.1.1980>.6.1.1980</A>   OR                                CORE
        <A href=dpans16.htm#16.6.2.1985>16.6.2.1985</A>   ORDER                             SEARCH EXT
          <A href=dpans6.htm#6.1.1990>.6.1.1990</A>   OVER                              CORE
          <A href=dpans6.htm#6.2.2000>.6.2.2000</A>   PAD                               CORE EXT
        <A href=dpans10.htm#10.6.1.2005>10.6.1.2005</A>   PAGE                              FACILITY
          <A href=dpans6.htm#6.2.2008>.6.2.2008</A>   PARSE                             CORE EXT
          <A href=dpans6.htm#6.2.2030>.6.2.2030</A>   PICK                              CORE EXT
          <A href=dpans6.htm#6.1.2033>.6.1.2033</A>   POSTPONE                          CORE
        <A href=dpans12.htm#12.6.2.2035>12.6.2.2035</A>   PRECISION                         FLOATING EXT
        <A href=dpans16.htm#16.6.2.2037>16.6.2.2037</A>   PREVIOUS                          SEARCH EXT
          <A href=dpans6.htm#6.2.2040>.6.2.2040</A>   QUERY                             CORE EXT
          <A href=dpans6.htm#6.1.2050>.6.1.2050</A>   QUIT                              CORE
        <A href=dpans11.htm#11.6.1.2054>11.6.1.2054</A>   R/O         <B>r-o</B>                   FILE
        <A href=dpans11.htm#11.6.1.2056>11.6.1.2056</A>   R/W         <B>r-w</B>                   FILE
          <A href=dpans6.htm#6.1.2060>.6.1.2060</A>   R>          <B>r-from</B>                CORE
          <A href=dpans6.htm#6.1.2070>.6.1.2070</A>   R@          <B>r-fetch</B>               CORE
        <A href=dpans11.htm#11.6.1.2080>11.6.1.2080</A>   READ-FILE                         FILE
        <A href=dpans11.htm#11.6.1.2090>11.6.1.2090</A>   READ-LINE                         FILE
          <A href=dpans6.htm#6.1.2120>.6.1.2120</A>   RECURSE                           CORE
          <A href=dpans6.htm#6.2.2125>.6.2.2125</A>   REFILL                            CORE EXT
         <A href=dpans7.htm#7.6.2.2125>7.6.2.2125</A>   REFILL                            BLOCK EXT
        <A href=dpans11.htm#11.6.2.2125>11.6.2.2125</A>   REFILL                            FILE EXT
        <A href=dpans11.htm#11.6.2.2130>11.6.2.2130</A>   RENAME-FILE                       FILE EXT
          <A href=dpans6.htm#6.1.2140>.6.1.2140</A>   REPEAT                            CORE
        <A href=dpans11.htm#11.6.1.2142>11.6.1.2142</A>   REPOSITION-FILE                   FILE
        <A href=dpans12.htm#12.6.1.2143>12.6.1.2143</A>   REPRESENT                         FLOATING
        <A href=dpans14.htm#14.6.1.2145>14.6.1.2145</A>   RESIZE                            MEMORY
        <A href=dpans11.htm#11.6.1.2147>11.6.1.2147</A>   RESIZE-FILE                       FILE
          <A href=dpans6.htm#6.2.2148>.6.2.2148</A>   RESTORE-INPUT                     CORE EXT
          <A href=dpans6.htm#6.2.2150>.6.2.2150</A>   ROLL                              CORE EXT
          <A href=dpans6.htm#6.1.2160>.6.1.2160</A>   ROT         <B>rote</B>                  CORE
          <A href=dpans6.htm#6.1.2162>.6.1.2162</A>   RSHIFT      <B>r-shift</B>               CORE
          <A href=dpans6.htm#6.1.2165>.6.1.2165</A>   S"          <B>s-quote</B>               CORE
        <A href=dpans11.htm#11.6.1.2165>11.6.1.2165</A>   S"          <B>s-quote</B>               FILE
          <A href=dpans6.htm#6.1.2170>.6.1.2170</A>   S>D         <B>s-to-d</B>                CORE
         <A href=dpans7.htm#7.6.1.2180>7.6.1.2180</A>   SAVE-BUFFERS                      BLOCK
          <A href=dpans6.htm#6.2.2182>.6.2.2182</A>   SAVE-INPUT                        CORE EXT
         <A href=dpans7.htm#7.6.2.2190>7.6.2.2190</A>   SCR         <B>s-c-r</B>                 BLOCK EXT
        <A href=dpans17.htm#17.6.1.2191>17.6.1.2191</A>   SEARCH                            STRING
        <A href=dpans16.htm#16.6.1.2192>16.6.1.2192</A>   SEARCH-WORDLIST                   SEARCH
        <A href=dpans15.htm#15.6.1.2194>15.6.1.2194</A>   SEE                               TOOLS
        <A href=dpans16.htm#16.6.1.2195>16.6.1.2195</A>   SET-CURRENT                       SEARCH
        <A href=dpans16.htm#16.6.1.2197>16.6.1.2197</A>   SET-ORDER                         SEARCH
        <A href=dpans12.htm#12.6.2.2200>12.6.2.2200</A>   SET-PRECISION                     FLOATING EXT
        <A href=dpans12.htm#12.6.2.2202>12.6.2.2202</A>   SF!         <B>s-f-store</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.2203>12.6.2.2203</A>   SF@         <B>s-f-fetch</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.2204>12.6.2.2204</A>   SFALIGN     <B>s-f-align</B>             FLOATING EXT
        <A href=dpans12.htm#12.6.2.2206>12.6.2.2206</A>   SFALIGNED   <B>s-f-aligned</B>           FLOATING EXT
        <A href=dpans12.htm#12.6.2.2207>12.6.2.2207</A>   SFLOAT+     <B>s-float-plus</B>          FLOATING EXT
        <A href=dpans12.htm#12.6.2.2208>12.6.2.2208</A>   SFLOATS     <B>s-floats</B>              FLOATING EXT
          <A href=dpans6.htm#6.1.2210>.6.1.2210</A>   SIGN                              CORE
        <A href=dpans17.htm#17.6.1.2212>17.6.1.2212</A>   SLITERAL                          STRING
          <A href=dpans6.htm#6.1.2214>.6.1.2214</A>   SM/REM      <B>s-m-slash-rem</B>         CORE
          <A href=dpans6.htm#6.1.2216>.6.1.2216</A>   SOURCE                            CORE
          <A href=dpans6.htm#6.2.2218>.6.2.2218</A>   SOURCE-ID   <B>source-i-d</B>            CORE EXT
        <A href=dpans11.htm#11.6.1.2218>11.6.1.2218</A>   SOURCE-ID   <B>source-i-d</B>            FILE
          <A href=dpans6.htm#6.1.2220>.6.1.2220</A>   SPACE                             CORE
          <A href=dpans6.htm#6.1.2230>.6.1.2230</A>   SPACES                            CORE
          <A href=dpans6.htm#6.2.2240>.6.2.2240</A>   SPAN                              CORE EXT
          <A href=dpans6.htm#6.1.2250>.6.1.2250</A>   STATE                             CORE
        <A href=dpans15.htm#15.6.2.2250>15.6.2.2250</A>   STATE                             TOOLS EXT
          <A href=dpans6.htm#6.1.2260>.6.1.2260</A>   SWAP                              CORE
          <A href=dpans6.htm#6.1.2270>.6.1.2270</A>   THEN                              CORE
         <A href=dpans9.htm#9.6.1.2275>9.6.1.2275</A>   THROW                             EXCEPTION
         <A href=dpans7.htm#7.6.2.2280>7.6.2.2280</A>   THRU                              BLOCK EXT
          <A href=dpans6.htm#6.2.2290>.6.2.2290</A>   TIB         <B>t-i-b</B>                 CORE EXT
        <A href=dpans10.htm#10.6.2.2292>10.6.2.2292</A>   TIME&DATE   <B>time-and-date</B>         FACILITY EXT
          <A href=dpans6.htm#6.2.2295>.6.2.2295</A>   TO                                CORE EXT
        <A href=dpans13.htm#13.6.1.2295>13.6.1.2295</A>   TO                                LOCAL
          <A href=dpans6.htm#6.2.2298>.6.2.2298</A>   TRUE                              CORE EXT
          <A href=dpans6.htm#6.2.2300>.6.2.2300</A>   TUCK                              CORE EXT
          <A href=dpans6.htm#6.1.2310>.6.1.2310</A>   TYPE                              CORE
          <A href=dpans6.htm#6.1.2320>.6.1.2320</A>   U.          <B>u-dot</B>                 CORE
          <A href=dpans6.htm#6.2.2330>.6.2.2330</A>   U.R         <B>u-dot-r</B>               CORE EXT
          <A href=dpans6.htm#6.1.2340>.6.1.2340</A>   U<          <B>u-less-than</B>           CORE
          <A href=dpans6.htm#6.2.2350>.6.2.2350</A>   U>          <B>u-greater-than</B>        CORE EXT
          <A href=dpans6.htm#6.1.2360>.6.1.2360</A>   UM*         <B>u-m-star</B>              CORE
          <A href=dpans6.htm#6.1.2370>.6.1.2370</A>   UM/MOD      <B>u-m-slash-mod</B>         CORE
          <A href=dpans6.htm#6.1.2380>.6.1.2380</A>   UNLOOP                            CORE
          <A href=dpans6.htm#6.1.2390>.6.1.2390</A>   UNTIL                             CORE
          <A href=dpans6.htm#6.2.2395>.6.2.2395</A>   UNUSED                            CORE EXT
         <A href=dpans7.htm#7.6.1.2400>7.6.1.2400</A>   UPDATE                            BLOCK
          <A href=dpans6.htm#6.2.2405>.6.2.2405</A>   VALUE                             CORE EXT
          <A href=dpans6.htm#6.1.2410>.6.1.2410</A>   VARIABLE                          CORE
        <A href=dpans11.htm#11.6.1.2425>11.6.1.2425</A>   W/O         <B>w-o</B>                   FILE
          <A href=dpans6.htm#6.1.2430>.6.1.2430</A>   WHILE                             CORE
          <A href=dpans6.htm#6.2.2440>.6.2.2440</A>   WITHIN                            CORE EXT
          <A href=dpans6.htm#6.1.2450>.6.1.2450</A>   WORD                              CORE
        <A href=dpans16.htm#16.6.1.2460>16.6.1.2460</A>   WORDLIST                          SEARCH
        <A href=dpans15.htm#15.6.1.2465>15.6.1.2465</A>   WORDS                             TOOLS
        <A href=dpans11.htm#11.6.1.2480>11.6.1.2480</A>   WRITE-FILE                        FILE
        <A href=dpans11.htm#11.6.1.2485>11.6.1.2485</A>   WRITE-LINE                        FILE
          <A href=dpans6.htm#6.1.2490>.6.1.2490</A>   XOR         <B>x-or</B>                  CORE
          <A href=dpans6.htm#6.1.2500>.6.1.2500</A>   [           <B>left-bracket</B>          CORE
          <A href=dpans6.htm#6.1.2510>.6.1.2510</A>   [']         <B>bracket-tick</B>          CORE
          <A href=dpans6.htm#6.1.2520>.6.1.2520</A>   [CHAR]      <B>bracket-char</B>          CORE
          <A href=dpans6.htm#6.2.2530>.6.2.2530</A>   [COMPILE]   <B>bracket-compile</B>       CORE EXT
        <A href=dpans15.htm#15.6.2.2531>15.6.2.2531</A>   [ELSE]      <B>bracket-else</B>          TOOLS EXT
        <A href=dpans15.htm#15.6.2.2532>15.6.2.2532</A>   [IF]        <B>bracket-if</B>            TOOLS EXT
        <A href=dpans15.htm#15.6.2.2533>15.6.2.2533</A>   [THEN]      <B>bracket-then</B>          TOOLS EXT
          <A href=dpans6.htm#6.2.2535>.6.2.2535</A>   \           <B>backslash</B>             CORE EXT
         <A href=dpans7.htm#7.6.2.2535>7.6.2.2535</A>   \           <B>backslash</B>             BLOCK EXT
          <A href=dpans6.htm#6.1.2540>.6.1.2540</A>   ]           <B>right-bracket</B>         CORE
</PRE>
<P>

Available from the American National Standards Institute, 11 West 42nd
Street, Newyork, NY 10036
<P>

Other common implementation techniques include direct translation to code
and other types of tokens.
<P>

These terms are not defined in the Standard.  They are mentioned here for
historical continuity.
Collating Sequence:


<PRE>
! " # $ % & ' ( ) * + , - . / digits : ; < = > ? @ ALPHA [ \ ] ^ _ ` alpha { |
} ~
</PRE>



<HR>
<A href=dpans.htm#toc><IMG   src="up.gif" ></A>    Table of Contents
<P>
</BODY>
</HTML>

left.gif/       784017600   500   0     100644  167       `
GIF87a³€€€€€€€€€ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,\ð€I«½@¾Í»ÿÈôdiž&#êžªøÎdÌÒ³Ý¾*‚ê¼Ø®„ÙnFñ¨L­vLÊ°ö4q,ÓCÑº‘þª®kvÞ|›¸$2­Î²Élª¨G¯Û{“»þžÁø1;
notes.htm/      850760400   500   0     100644  5552      `
<HTML><HEAD>
<TITLE>DPANS94 editorial notes</TITLE>
</HEAD>

<BODY>
<hr>
<h3>Editorial Notes</h3>
<p>
<b>V3.2 - December 16, 1996</b>
<p>
RFIs (requests for interpretation) added by Anton Ertl. Minor changes 
in appearance of See: references in wordset glossaries.

<p>
<b>V3.1 - October 17, 1996</b>
<p>
Format of anchors changed so that Mosaic can see them.  File suffixes
changed from .html to .htm to be more compatible with DOS/Unix.

<p>
<b>V3.0 - September 14, 1996</b>
<p>

This is a modification of Norman E. Smith's rendering of the draft standard
(see 
his note below).  Four changes have been made: (a) some errors have been 
corrected, (b) minor changes in the style of HTML presentation have been 
made to make it (hopefully) more readable, (c) hundreds of  
crosslinks have been added, and (d) the naming conventions for the internal
sections of the document have been standardized so that it would be easy to
crosslink to this document.  
<p>
For example if I, or anyone, were writing a message
on comp.lang.forth and I wanted to crosslink to the standard definition of
CATCH then I would write something like 
<p>
a=href http://wherever.document.is.stored/dpans9.htm#9.6.1.0875
CATCH  
/a
<p>
except that the phrases /a and a=href http:... are enclosed in angle brackets.
<p>
The standard is broken into 40 files:
<p>
<ul>
<li>one file,
dpans.htm, holds the preface and table of contents;
<li>seventeen files hold the 17 sections of the standard, 
i.e. dpans1.htm thru 
dpans17.htm; 
<li>one file each for annexes B, C, D, E, and F, i.e. dpansb.htm 
thru dpansf.htm; 
<li>and seventeen files for annex A corresponding to the 17
sections of the standard, i.e. dpansa1.htm thru dpansa17.htm.  
</ul>
<p>

The 
subdivision of Annex A is the only irregularity in this scheme and this was
done both because it's not that hard to remember and also to break up what 
would 
otherwise be an unmanageably large annex.  Within each file every subsection, 
sub-subsection, and sub-sub-subsection, etc. is named following the same 
conventions 
that the draft paper document uses.
<p>

The only problem with this whole scheme is that some of the files, in 
particular, sections 3 and 6, are large and therefore referencing 
them online can take a long time.  As a practical matter I would recommend 
downloading all the files and using an html browser, like
netscape, to access locally.  Another solution 
that I am contemplating would be the breaking out of word definitions from 
sections 6 thru 17 into individual files.  This would entail a more 
complicated cross-referencing, but I think it would still be manageable.
It would also mean that online access might become rapid.
<p>

Mark Andrew Amerman
<br>
mandrewa@cais.com

<p>
<hr>
<P>

<B>V2.1 - September 1, 1995</B> 
<P>

This HTML version of this document was prepared by:
<P>

Norman E. Smith
<BR>
72745,1566@Compuserve.com
<P>

It was prepared from the Microsoft Word document posted by
the Technical Committee in early 1995. See their 
<A href=dpans94.txt>readme</A>
file for the details and conditions of using the
postings. The Microsoft Word and Postscript versions of the
document are available on ftp://ftp.uu.net/vendor/minerva...
and a Postscript and 
FPC hyperlinked ASCII version are
also available on Taygeta.
<P>

This second version has extensive
hyperlinks added. These are content related. The 'See:'
references to words link directly to their glossary
entry for example. Because the original document was well structured
and the conversion was to a proper HTML file, much of the 
hyperlink generation can be automated. Even though little
had to be done manually, the large number of links and anchors 
caused the additional was more work than I expected.
<P>

The files that make up this document were
created using Standardized Generalized Markup Language (SGML)
based autotaging software. For this reason, all of the files
also parse correctly with the current HTML Document Type
Definitions (DTDs). 
<P>

I am planning a third pass at the document to
do a proper SGML representation of the word glossaries
and additional links in the text. At that
point, I will be able to generate a word glossary in just about
any format. 
<P>

The process of spliting the document into managable (about 20k)
files, generating the Table of Contents, and inserting the
structural hyperlinks was done with a program written in Until. 
<A href=ftp://taygeta.oc.nps.navy.mil/pub/Forth/Reviewed/until22.zip>Until</A>
is my almost-Forth, written in very generic C, that is also available 
on Taygeta. The Until 
<A href=http://taygeta.oc.nps.navy.mil/pub/until/until.html>Reference
Manual</A> can be browsed on Taygeta as well.
<P>

Lastly, thanks to the X3J14 Technical Committee for making the
Word version of the document available and to Skip Carter for
making space available on Taygeta for not only this document, but
the wealth of other Forth infomation available there.
<P>

<B>Changes:</B>
<P>

03/30/95 - V2.0 - Added hundreds of anchors and links. 
<P>

02/28/95 - V1.2 - The 02/23/95 version used an old version of the table of
contents file with incorrect hyperlinks. This version corrects that. Sorry!
<P>

02/23/95 - V1.1- Added title page from original document that was lost during
initial
conversion per request of the Technical Committee.
<P>

Enjoy!
<BR>
Norman Smith
<P>
<hr>
</BODY>
</HTML>

rfilist.htm/    850789920   500   0     100644  905       `
<HTML><HEAD>
<TITLE>DPANS94 editorial notes</TITLE>
</HEAD>

<BODY>

<h3>ANS Forth X3J14 Technical Committee responses 
to requests for interpretation</h3>

<hr>
<p>
<a href=a0001.htm>RFI 0001</a>: regarding the "flag" returned 
by <a href=dpans11.htm#11.6.1.2090>READ-LINE</a> at end of file.
<br>
<a href=a0002.htm>RFI 0002</a>: search orders in which a given wordlist
occurs more than once.
<br>
<a href=a0003.htm>RFI 0003</a>: What's allowed between 
<a href=dpans6.htm#6.1.1000>CREATE</a> and 
<a href=dpans6.htm#6.1.1250>DOES></a>
<br>
<a href=a0004.htm>RFI 0004</a>: standard punctuation for double-cell numbers.
<br>
<a href=a0005.htm>RFI 0005</a>: initiation semantics.
<br>
<a href=a0006.htm>RFI 0006</a>: Writing to Input Buffers.
<br>
<a href=a0007.htm>RFI 0007</a>: distinction between "immediacy" and
"special compilation semantics"
<P>
<hr>
</BODY>
</HTML>

right.gif/      784017600   500   0     100644  169       `
GIF87a³€€€€€€€€€ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,^ð€I«½@¾óºÿà‡LÛažhz"#Pª0Ê’qmÎ®]ã¯Ìî­Þ
ÀBÀxGJ1…Tµ”¿[0y‰6™Ïjê¤h}´î—Éev€a�³¬çÚä4\J*Úïøâ$ÏÏg0€;
up.gif/         784017600   500   0     100644  170       `
GIF87a³€€€€€€€€€ÀÀÀ€€€ÿÿÿÿÿÿÿÿÿÿÿÿ,_ð€I«µòéÍ;GÓsŒdiŽˆgK¦¡+Ã«‹Ø*k¦zI÷¯Úé7iŠ±x úT+ 3X‘æž–ãëJÍb…(�Å•!Áæ/3=Mo“î7:þKÙïxü$Ïç$�;