[Win32forth-cvs] win32forth/doc p-block.htm, NONE, 1.1 p-index.htm, 1.18, 1.19

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/win32forth/win32forth/doc
In directory sc8-pr-cvs9.sourceforge.net:/tmp/cvs-serv25593/win32forth/doc

Modified Files:
	p-index.htm 
Added Files:
	p-block.htm 
Log Message:
gah:Added documentation

--- NEW FILE: p-block.htm ---
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="GENERATOR" content="dexh v03">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>
 W32F block</title><style><!--
h1           { font-family: Tahoma; font-size: 24pt; font-weight: bold }
h2           { font-family: Tahoma; font-size: 18pt; font-weight: bold } -->
</style>
</head>
<body><h1 align="center">
<a href="mailto:win...@ya...?subject=DOC:Doc error in $Id: p-block.htm,v 1.1 2006/10/17 08:52:18 georgeahubert Exp $">
<img border="0" src="TELLUS.gif" align="left" width="32" height="32"></a>
<img border="0" src="FORTHPRO.gif"
width="32" height="32">&nbsp;&nbsp;Win32Forth</h1>
<hr /><h1>Using the Block Wordset
</h1><hr /><p>Win32Forth implements a virtual block system, based on the ANSI standard Block
and Block extension wordsets. <br />
The block words are not loaded by default and have to be included. The file
BLOCK.F is in the lib folder (some older versions of W32F placed it in the extras
folder). <br />
The constants B/BUF, and #BUFFERS control the block size, and the number of
buffers the system uses. &nbsp;These are defaulted to 1024 byte blocks, and
8 buffers. &nbsp;A true LRU (least recently used) buffer allocation mechanism
is used, implemented as a bubble up buffer stack. &nbsp;The least recently used
buffer is always on the bottom of the stack. &nbsp;As buffers are used or
re-used, they are bubbled immediately up to the top of the stack, destined
to settle to the bottom of the stack if the same record is not accessed
again. <br />&nbsp;Blocks are stored in a blockfile (normally with the .blk extension,
although some forths use .fb) which is set by the words set-blockfile,
open-blockfile or create-blockfile and closed by close-blockfile. Only one
blockfile is active at any one time, open-blockfile and create-blockfile
automatically close the current one prior to setting themselves as the current
blockfile. <br />
<b>&nbsp;NOTE </b>&nbsp;set-blockfile does not close the current blockfile.
</p><h2>Glossary
</h2><pre><b><a name="0">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1024 constant b/buf &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Length of each block.
</p><pre><b><a name="1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;64 constant c/l &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Number of characters per line.
</p><pre><b><a name="2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;8 constant #buffers &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Number of block buffers.
</p><pre><b><a name="3">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-1 &nbsp;&nbsp;&nbsp;value blockhandle &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>The handle of the current block file, or -1 if no current block file.
</p><pre><b><a name="4">variable blk &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( -- a-addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></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 SOURCE-ID, if SOURCE-ID is available. An ambiguous
condition exists if a program directly alters the contents of BLK.
</p><pre><b><a name="5">variable scr &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( -- a-addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block ext
</a></b></pre><p>a-addr is the address of a cell containing the block number of the block most
recently listed.
</p><pre><b><a name="6">: save-buffers &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></pre><p>Transfer the contents of each updated block buffer to mass storage.
Mark all buffers as unmodified.
</p><pre><b><a name="7">: buffer &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( u -- a-addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></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. <br />
If block u is already in a block buffer, a-addr is the address of that block buffer. <br />
If block u is not already in memory and there is an unassigned buffer, a-addr is the
address of that block buffer. <br />
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 UPDATEd, transfer
the block to mass storage. a-addr is the address of that block buffer.
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><pre><b><a name="8">: empty-buffers &nbsp;&nbsp;&nbsp;&nbsp;( -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block ext
</a></b></pre><p>Unassign all block buffers. Do not transfer the contents of any updated
block buffer to mass storage.
</p><pre><b><a name="9">: flush &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></pre><p>Perform the function of SAVE-BUFFERS, then unassign all block buffers.
</p><pre><b><a name="10">: update &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></pre><p>Mark the current block buffer as modified. An ambiguous condition exists if there
is no current block buffer. <br />
Update does not write the block to the disc.
</p><pre><b><a name="11">: block &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( u -- a-addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></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. <br />
If block u is already in a block buffer, a-addr is the address of that block buffer. &nbsp;<br />
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. <br />
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 UPDATEd, 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. <br />
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><pre><b><a name="12">: list &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( u -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block ext
</a></b></pre><p>Display block u in the console in a 16 line format. Store u in SCR. <br />
An error occurs if u is greater than the number of blocks in the current blockfile.
</p><pre><b><a name="13">: wipe &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( u -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Erase the specified block to blanks.
</p><pre><b><a name="14">: set-blockfile &nbsp;&nbsp;&nbsp;&nbsp;( fileid -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Make fileid the current blockfile.
</p><pre><b><a name="15">: load &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( i*x u -- j*x ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block
</a></b></pre><p>Save the current input-source specification. Store u in BLK (thus making block
u the input source and setting the input buffer to encompass its contents), set
&gt;IN 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.
An ambiguous condition exists if u is zero or is not a valid block number.
</p><pre><b><a name="16">: thru &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( i*x u1 u2 -- j*x ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ ANSI &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block ext
</a></b></pre><p>LOAD the mass storage blocks numbered u1 through u2 in sequence. Other stack
effects are due to the words LOADed.
</p><pre><b><a name="17">: close-blockfile &nbsp;&nbsp;( -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Close the current blockfile, flushing any updated buffers. Set the current blockfile
to no file.
</p><pre><b><a name="18">: open-blockfile &nbsp;&nbsp;&nbsp;( &quot;&lt;spaces&gt;'filename'&quot; ) &nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Close the current blockfile. Open the file and make it the current block file.
</p><pre><b><a name="19">: create-blockfile &nbsp;( u &quot;&lt;spaces&gt;'filename'&quot; ) \ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>Close the current blockfile. Create a file of u blocks long, initialise the
blocks to blanks and make it the current blockfile.
</p><pre><b><a name="20">: #blocks &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( -- u ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Block extra
</a></b></pre><p>u is the number of blocks in the current blockfile.
</p><hr><p>Document $Id: p-block.htm,v 1.1 2006/10/17 08:52:18 georgeahubert Exp $</p>
</body></html>

Index: p-index.htm
===================================================================
RCS file: /cvsroot/win32forth/win32forth/doc/p-index.htm,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -d -r1.18 -r1.19
*** p-index.htm	25 Sep 2006 11:42:57 -0000	1.18
--- p-index.htm	17 Oct 2006 08:52:18 -0000	1.19
***************
*** 141,144 ****
--- 141,145 ----
    <li><a href="p-float.htm">Floating point words in Win32Forth</a></li>
    <li><a href="p-module.htm">Using the Module Wordset</a></li>
+   <li><a href="p-block.htm">Using the Block Wordset</a></li>
    <li><a href="p-interpif.htm">Interpretive conditionals in Win32Forth</a></li>
    <li><a href="p-task.htm">Using the Task Wordset</a></li>