home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / FORTH038.ZIP / FORTH.DOC < prev    next >
Text File  |  1993-07-23  |  58KB  |  1,475 lines

  1.  
  2.  
  3.                    Forth/2 Preliminary Documentation
  4.                             May 11, 1993
  5.  
  6.  
  7. Forth/2 is a fully 32-bit, native Forth for OS/2 2.0.  It requires an
  8. 80386SX or compatible microprocessor, and OS/2 2.0 or subsequent
  9. versions.
  10.  
  11. Forth/2 was created specifically for OS/2 using MASM 6.0 Currently it is
  12. a text-mode application which can be run either in a full screen or in a
  13. window.  It presently does not conform to any single Forth standard.
  14. Most of the major Forth functions are included.
  15.  
  16.  
  17.  
  18.  
  19.                            Table of Contents
  20.  
  21. 0.   Introduction
  22.  
  23. 1.   Using Forth/2
  24. 1.1  Installing Forth/2
  25. 1.2  Starting Forth/2
  26. 1.3  Basic information about Forth/2
  27. 1.4  Quitting Forth/2
  28. 1.5  Executing OS/2 Commands from Forth/2
  29. 1.6  Creating and Loading Forth Source Code
  30. 1.7  Error Detection
  31.  
  32. 2.   For Beginners
  33.  
  34. 3.   Special Functions IN Forth/2
  35. 3.1  Case Statements
  36. 3.2  TO Variables (or VALUE's)
  37. 3.3  String Handling Words
  38. 3.4  Threads
  39. 3.5  Arrays and Structures
  40. 3.6  Vocabularies
  41. 3.7  Local Variables
  42.  
  43. 4.   List of Words
  44. 4.1  Parameters
  45. 4.2  Parameter Naming Conventions
  46. 4.3  List of Word Definitions (INCOMPLETE)
  47.  
  48. 5.   Technical Description
  49. 5.1  Internals
  50. 5.2  OS/2 Interface
  51. 5.3  USER Variables and Multi-Tasking
  52. 5.4  TO Variables (VALUE's)
  53. 5.5  Vocabularies
  54. 5.6  Specifications and Limits
  55.  
  56.  
  57. 6.   Compatibility Issues
  58. 7.   Where to send comments/suggestions
  59.  
  60.  
  61.  
  62. 0.  INTRODUCTION
  63.  
  64. Forth is an interactive, hierarchical programming language.  Forth is a
  65. collection of functions which can be combined to create new functions,
  66. which in turn can be used in other functions.  A "program" in Forth is
  67. simply a word which performs a series of these functions.
  68.  
  69. For example, most books on programming show you how to create a minimal
  70. program in a particular language, one which simply types the words
  71. "Hello, world!" on the screen.  In Forth, this would be:
  72.  
  73.    : HELLO   ." Hello, world!" ;
  74.  
  75. Then, typing the word HELLO and tapping the Enter key will print the
  76. message.  The word  :  defines the new word HELLO, and defines its
  77. function to be all the words following up to the  ; . In this case, the
  78. only function it performs is  ."  (pronounced "dot-quote"), which 
  79. simply types the text to the screen up to the ending  " .
  80.  
  81. All the words  :  ."  and  "  are functions which reside in Forth's 
  82. vocabulary, the list of defined functions.  Then,  HELLO  was simply 
  83. added to this list of functions.  To see other available functions,
  84. type  WORDS  and tap the Enter key.
  85.  
  86. This documentation cannot hope to explain Forth to newcomers as well as 
  87. others have.  Two very readable and highly recommended books which
  88. explain Forth are:
  89.  
  90.    Starting Forth (2nd ed.) by Leo Brodie
  91.    Thinking Forth  also by Leo Brodie.
  92.  
  93. Look for them in your local library or bookstore, or obtain these and
  94. other books by writing or calling FORTH, Inc. at:
  95.  
  96.    FORTH Inc.
  97.    <I have to find their address>
  98.  
  99.  
  100.    John D. Hall, President
  101.    Forth Interest Group
  102.    P.O. Box 2154
  103.    Oakland, CA  94621
  104.    (510) 893-6784, Fax (510) 535-1295
  105.  
  106.  
  107.  
  108.  
  109. 1.  Using Forth/2
  110.  
  111. 1.1  Installing Forth/2
  112.  
  113. The Forth/2 beta is currently distributed as a single .ZIP (compressed) 
  114. file called FORTHxxx.ZIP where xxx is the version number (currently at 
  115. xxx=028).  Copy this file into any folder, and use PKWare's pkunzip
  116. utility or equivalent to uncompress the files.  
  117.  
  118. Forth/2 reads and compiles the file FORTH.INI upon startup.  This file
  119. helps minimize the size of the FORTH.EXE file while maximizing the 
  120. ability to customize Forth/2.  Make sure this file is in the same 
  121. directory that FORTH.EXE is called from.
  122.  
  123.  
  124.  
  125. 1.2  Starting Forth/2
  126.  
  127. To run Forth/2 from the OS/2 command line, simply change to the
  128. directory containing FORTH.EXE and FORTH.INI and type:
  129.  
  130.    FORTH
  131.  
  132. Or, create an OS/2 .CMD file to automate this process.  If you have 
  133. installed Forth/2 in a directory called FORTH2 on drive  C: then create
  134. a file called FORTH.CMD as follows:  
  135.  
  136.    REM FORTH.CMD  -  Starts Forth/2
  137.    C:
  138.    CD \FORTH2
  139.    FORTH
  140.  
  141. From the WorkPlace Shell, simply open the folder containing FORTH.EXE
  142. and FORTH.INI and double-click on FORTH.EXE.  To set it up to run in a
  143. window or in a full screen, bring up the menu for this object with Mouse
  144. Button 2, and select Open-->Settings, click on Session, and check either 
  145. the Windowed or Full Screen buttons to select.  
  146.  
  147.  
  148.  
  149. 1.3  Basic information about Forth/2
  150.  
  151. All Forth/2 commands are case insensitive.  When new definitions are 
  152. added to the dictionary, the letters are converted to uppercase first.  
  153. To see a listing of functions available in Forth/2, type Words then tap 
  154. the Enter key.
  155.  
  156. In the Words listing, you will see a fairly long list of words in the 
  157. Forth vocabulary, followed by the words available in the System 
  158. vocabulary.  The System vocabulary contains the names of many OS/2 
  159. system calls which would otherwise clutter up the main Forth dictionary.  
  160.  
  161. To remove these system calls from the Words listing, type Forth ONLY and 
  162. tap the Enter key.  To see or use the system calls again, type System 
  163. and they will reappear.  
  164.  
  165. See Section 3.6  VOCABULARIES for more information.
  166.  
  167. You may also look up individual words from the Forth prompt.  If the
  168. file FORTH2.DOC (this file) is in the same directory that FORTH.EXE
  169. is in, type
  170.  
  171.    VIEW wordname
  172.  
  173. to get a brief description of a word and what parameters it requires
  174. and leaves on the stack.  Try  VIEW VIEW for example.
  175.  
  176. Use the function key F3 to recall the previous command, or F1 to recall
  177. the previous command one letter at a time.
  178.  
  179.  
  180.  
  181. 1.4  Quitting Forth/2
  182.  
  183. To exit from Forth/2, type
  184.  
  185.     BYE
  186.  
  187. and tap the Enter key.
  188.  
  189. If Forth/2 has locked up, or is caught in an endless (or very long) 
  190. loop, use Ctrl-C to exit the program.  
  191.  
  192.  
  193.  
  194. 1.5  Executing OS/2 Commands from Forth/2
  195.  
  196. To temporarily exit to the OS/2 command line prompt, type
  197.  
  198.     CommandPrompt
  199.  
  200. and tap the <Enter> key.  Feel free to redefine this to a shorter word.  
  201. When you have finished using OS/2 commmands, type 
  202.  
  203.     EXIT
  204.  
  205. and tap the <Enter> key to return to Forth/2.  The state of Forth/2 will
  206. be preserved.
  207.  
  208.  
  209. For frequently used system calls, you may wish to have OS/2 run the program
  210. directly.  To invoke an editor from Forth/2, and pass it the name of a
  211. file to edit, create the following word:
  212.  
  213.     : ED  ( -- )  ARGS" filename.4th"  SHELL" editor.exe" ;
  214.  
  215. You must give the exact path of the editor.exe program.  Omit the ARGS"
  216. if you do not want to pass the program any arguments.  To create a word 
  217. called ED" <filename>" which will edit the file after it, create this 
  218. word:  
  219.  
  220.     : ED" ( name-- )  [COMPILE] ARGS"    SHELL" editor.exe" ;
  221.  
  222.  
  223. To have OS/2's command shell execute a command, such as copy, del, start,
  224. etc., use a /C in front of the arguments passed to CMD.EXE.  For example,
  225. to create a Forth-based Copy command, do the following:
  226.  
  227.     : COPY  " /C COPY "   Arguments "MOVE
  228.             BL Word       Arguments "CAT
  229.             "  "          Arguments "CAT
  230.             BL Word       Arguments "CAT  CommandShell ;
  231.  
  232. To copy a file  test.4th  to  a:test.4th, type:
  233.  
  234.     COPY test.4th a:test.4th
  235.  
  236. See Section 3.3 on string handling for more information.
  237.  
  238.  
  239.  
  240. 1.6  Creating and Loading Forth Source Code
  241.  
  242. Create Forth definitions directly from the command line, or create an 
  243. ASCII sequential file using your favorite text editor.  To load in the 
  244. file, use the following word:  
  245.  
  246.     INCLUDE" FileName.TXT"
  247.  
  248. You may freely nest INCLUDE" inside other INCLUDE"ed files.  However, 
  249. when compiled, the files must not alter the stack, either by requiring 
  250. numbers or by leaving extra numbers on the stack.  
  251.  
  252. You may also use OS/2's cut and paste ability to copy just a few words 
  253. from your editor, paste them into a windowed Forth/2 session, and try 
  254. them out until they work correctly.  
  255.  
  256. The file FORTH.INI contains basic definitions required by most Forth
  257. programmers, as well as a few utility programs like  MORE"  and  DIR.
  258. You may add your own programs to this file, or make any changes you 
  259. desire.  However, it is recommended that you instead use the
  260. STARTUP.4TH file for any customizations.  This way, you will avoid 
  261. having to reconcile the latest version of Forth/2 with your own 
  262. changes.  
  263.  
  264. Use ECHO ON and ECHO OFF within .4TH files to echo portions of a 
  265. document to the screen while they are being loaded.
  266.  
  267. When debugging programs it is common to load and re-load a program many
  268. times.  Avoid cluttering up the dictionary by using the word  FORGET.
  269. Use the command  FORGET <word>  to remove all definitions from <word> 
  270. onward.  
  271.  
  272.  
  273.  
  274. 1.7.  Error Detection
  275.  
  276. Unlike DOS, OS/2 catches any reads or writes to memory outside of the
  277. application's allocated space.  This helps keep applications protected
  278. from one another, and notifies you that you have a bug.  Almost nothing 
  279. you can do will crash anything but the one Forth/2 session.
  280.  
  281. All this protection is nice, but when things go wrong there is no way
  282. to trace back what happened, nor examine the values of specific memory
  283. locations.  (OS/2 has system calls to do this, but they have not been
  284. utilized in Forth/2 yet.)  Fortunately, Forth makes it so easy to test 
  285. out small chunks of code that wild memory references can be narrowed 
  286. down to the culprit quickly.
  287.  
  288. Note: These exceptions will handled gracefully in a future release.
  289.  
  290.  
  291.  
  292. 2.  FOR BEGINNERS
  293.  
  294. Under construction!  If you would like to know how Forth works, find a
  295. book on programming in Forth at your local library.  Or, obtain a file
  296. from an Internet ftp site which describes how to use Forth.
  297.  
  298. The ftp site asterix.inescn.pt (192.35.246.17) contains a great deal of
  299. information about Forth and Forth programs.  Look in the directory
  300. /pub/forth.
  301.  
  302.  
  303.  
  304. 2.1  Forth Structure and Syntax
  305.  
  306. The following are some basic statements about Forth's stucture and
  307. syntax:
  308.  
  309.   Forth is made up of a DICTIONARY of words.
  310.  
  311.   The DICTIONARY can be organized into separate VOCABULARIES.
  312.  
  313.   Each word in the dictionary performs some kind of function.
  314.  
  315.   All words and numbers must be separated by at least one SPACE.
  316.  
  317.   To use a word or series of words, type them in and tap Enter.
  318.  
  319.   Some words, like CONSTANTs, simply return a value.
  320.  
  321.   Other words perform various functions.
  322.  
  323.  
  324.   Forth is STACK-ORIENTED, and uses Reverse Polish Notation.
  325.  
  326.   The stack is used to pass PARAMETERS to words.
  327.  
  328.   Many words OPERATE on a certain number of parameters on the stack,
  329.    THEN RETURN zero or more parameters on the stack.
  330.  
  331.   For example, the word '+' adds two numbers from the stack, leaving one.
  332.  
  333.   To see the CONTENTS OF THE STACK, use the word  .S
  334.  
  335.  
  336.   The defining word  :  CREATES a new word in the dictionary.
  337.  
  338.   Create this:   : TEN+  10 + ;   Try:  100 TEN+ .S   -10 TEN+ .S
  339.  
  340.   The word  :  is just another word in the dictionary, which creates
  341.     a dictionary entry for the word which follows it, and defines
  342.     the word's funtion to be to perform all the words which follow
  343.     it up to the  ;
  344.  
  345.   Forth allows ANY ASCII characters to be used in word names.
  346.  
  347.   Other words, like VARIABLE <variable_name>  or
  348.            <number> CONSTANT <constant_name>  also create new words.
  349.  
  350.   VARIABLE's push the address where the variable is stored onto the stack.
  351.   To FETCH the contents of the variable, use          <variable_name> @
  352.   To STORE a number into the variable, use   <number> <variable_name> !
  353.   The word  @  is pronounced "FETCH", and  !  is pronounced "STORE".
  354.  
  355.   To print and remove the number from the top of the stack, use  . (DOT)
  356.  
  357.   One convention in Forth is to use  .  in any word which prints things.
  358.  
  359.  
  360. Planned sections:
  361.  
  362. 2.2  Simple math, .S, ."
  363. 2.3  : routines, IF...THEN
  364. 2.4  DO...LOOP   BEGIN...AGAIN
  365. 2.5  Number formatting
  366. 2.9  Making something work inside  :  definitions (e.g. COPY)
  367.  
  368.  
  369.  
  370.  
  371. 3.  SPECIAL FUNCTIONS IN FORTH/2
  372.  
  373. This section describes special words available in Forth/2.
  374.  
  375.  
  376. 3.1  CASE STATEMENTS
  377.  
  378. CASE statements are for when you evaluate a number of different options, 
  379. as in typing the day of the week.  Try the following word:
  380.  
  381. : DAY ( n ) CASE  1 OF  ." Monday"       ENDOF
  382.                   2 OF  ." Tuesday"      ENDOF
  383.                   3 OF  ." Wednesday"    ENDOF
  384.                   4 OF  ." Thursday"     ENDOF
  385.                   5 OF  ." Friday"       ENDOF
  386.                   6 OF  ." Saturday"     ENDOF
  387.                   7 OF  ." Sunday"       ENDOF
  388.                         ." Day " . ." ?" ENDCASE ;
  389.  
  390. Simply type  5 DAY  and it will print "Friday".
  391.  
  392. Note that you need a  DROP  or a similar effect between the last ENDOF 
  393. and the ENDCASE, which differs from other implementations of CASE..ENDOF.
  394.  
  395.  
  396.  
  397. 3.2  TO VARIABLES (or VALUE's)
  398.  
  399. TO variables help make Forth simpler to use and to read.  They are most
  400. useful when you fetch a value much more often then you store into that
  401. variable.
  402.  
  403. To create a TO variable, simply type:
  404.  
  405.     INTEGER X_LOC
  406.  
  407. and it is initialized to 0.  To examine the value of X_LOC, simply type:
  408.  
  409.     X_LOC .
  410.  
  411. No @ is necessary.  To store a new value into X_LOC simply type
  412.  
  413.    100 TO X_LOC
  414.  
  415. Then,  X_LOC .  will show 100.  To add to a TO variable, use +TO as in:
  416.  
  417.    50 +TO X_LOC
  418.  
  419. Then,  X_LOC .  will show 150.  To create a TO variable initialized 
  420. with a certain value, use:
  421.  
  422.     1020 TO INTEGER Taxes
  423.  
  424.  
  425. Create arrays of integers with another word:
  426.  
  427.    100 INTARRAY XP[]    ( Creates an array called XP[] of 100 elements )
  428.  
  429.    100 0 DO  100 RND  I TO XP[]  LOOP   ( Store random numbers into XP )
  430.  
  431.    0  100 0 DO  I XP[] +  LOOP          ( Calculates the sum of all XP )
  432.  
  433. And, using  n index +TO XP[]  will add n to the indexed integer.
  434.  
  435. You can also create STRING TO variables.  See section 3.3.
  436.  
  437.  
  438.  
  439. 3.3  STRING HANDLING WORDS
  440.  
  441. All of the string words such as  ."  can be used outside colon definitions.
  442. A number of words have been included with Forth/2 to facilitate string
  443. handling.  
  444.  
  445.  
  446. 3.3.1  Creating and Typing Strings
  447.  
  448. To create a string constant, use the word " as follows:  
  449.  
  450.     " April 4, 1999"  "CONSTANT Deadline
  451.  
  452. Then, use  ".  (quote-dot) to type it out:
  453.  
  454.     Deadline ".
  455.  
  456. Develop your own synonyms for ". like  @Type  or  $.  etc.  Or, a
  457. simpler way to create a string constant is like this:
  458.  
  459.     Call" Bill Clinton" President
  460.  
  461. To create a zero-terminated string, such as for use with OS/2 system
  462. calls, use 0" as follows:
  463.  
  464.     : Invoice_File   0" Invoices.DAT" ;
  465.  
  466. Then, use  0".  to type the string out:
  467.  
  468.     Invoice_File 0".
  469.  
  470. or either type or load a file:
  471.  
  472.     0" Calendar.4TH" MORE
  473.     0" Calendar.4TH" INCLUDE
  474.  
  475. Use  0"COUNT  to obtain the size of a 0-terminated string.  In the
  476. example below, the 0" string is counted, then moved into TempStr as
  477. a counted string with MOVE>"
  478.  
  479.     CREATE TempStr   80 ALLOT
  480.     0" FileName.TXT"  0"COUNT  TempStr  MOVE>"
  481.  
  482.  
  483. You may want to terminate a regular counted string with a zero
  484. (if you have alloted room beyond the string).  To do this, use
  485.  
  486.     CREATE StrA  80 ALLOT
  487.     " To be zero-terminated"  StrA  "MOVE
  488.     StrA 0-Terminate
  489.     StrA W+ 0".               \ Skip length and use 0". to print
  490.  
  491. These words all work in colon definitions as well.
  492.  
  493.  
  494. 3.3.2  Copying and Concatenating Strings
  495.  
  496. The word  "MOVE  will move a counted string to another area of memory.
  497. To copy a string to another memory area, do the following:
  498.  
  499.    ( Make room for strings up to 80 characters long )
  500.    VARIABLE StringBuf  80 ALLOT
  501.  
  502.    Call" Warning: " WarnMsgBeg
  503.  
  504.    : InitWarning   WarnMsgBeg StringBuf "MOVE ;
  505.  
  506.    : TempWarning   InitWarning
  507.                    " Temperature over limit!"  StringBuf "CAT ;
  508.  
  509.    : PresWarning   InitWarning
  510.                    " Pressure overload!"       StringBuf "CAT ;
  511.  
  512.  
  513.    TempWarning  StringBuf ".   ( Will print the warning message )
  514.  
  515.  
  516. The word  "CAT  will add one string to the end of a second string.
  517. It accepts two strings on the stack, ( string1 string2 -- ) which are 
  518. both counted-strings, and adds  string1  to the end of  string2.
  519.  
  520. Because both  WORD  and  "  return the address of a counted string, most
  521. string handling words act upon a single address.  That address points to
  522. a 32-bit length, followed by the characters which make up the string.
  523. However, it is often required to manipulate a string which does not have
  524. a length at the address, but instead the length is on the stack.  To use 
  525. words like "CAT or =" with a string and length, first move it to a
  526. temporary string buffer with the word MOVE>" as follows:
  527.  
  528.     0" First Second Third Word"  6  StringBuf  MOVE>"
  529.  
  530.     StringBuf ".                 \ Will type "First "
  531.  
  532. The above code copies the first six charcters from the 0" string to
  533. StringBuf, because 0" returns the address of the first charcter of the
  534. string.
  535.  
  536. The word  MOVE>"  will copy a character string of a given length to an
  537. address and save it as a counted string.
  538.  
  539.     MOVE>"  ( address length dest_address -- )
  540.  
  541.  
  542. 3.3.3  Comparing Strings
  543.  
  544. You can check if two strings are equal with  ="  which accepts the
  545. addresses of two counted strings, and returns true or false if they are
  546. equal or not.  This word is case insensitive, so
  547.  
  548.  
  549.    Call" AbC" String1
  550.    String1  " aBc"  ="
  551.  
  552. ( Note that you cannot type in from the command line two quoted strings
  553. in a row, because the second is parsed into the same location as the
  554. first one, overwriting it.)
  555.  
  556. Often, however, you will have to compare one string, which is given as
  557. an address and length, with another counted string.  Instead of using
  558. MOVE>"  every time you wish to compare the string with another 
  559. (counted) string, use the word  =STRING  as follows:
  560.  
  561.    address length  " Compare String"  =STRING  IF  ...  ELSE  ...  THEN
  562.  
  563.  
  564.  
  565.  
  566. 3.3.4  String TO Variables
  567.  
  568. String  TO  variables are also available.  They are used in the same way
  569. as regular  TO  variables:
  570.  
  571.     STRING S1                         \ Create string S1
  572.  
  573.     " This is String 1" TO S1         \ Store string into S1
  574.  
  575.     " Initial String 2" TO STRING S2  \ Create string with initial value
  576.  
  577.     " Plus some extra" +TO S2         \ Adds "Plus some..." to end of S2
  578.  
  579.     S1 ".    S2 ".                    \ Type contents of strings S1 and S2
  580.  
  581.  
  582.  
  583.  
  584.  
  585. 3.4  THREADS
  586.  
  587. Threads are separate processes which run concurrently with other 
  588. programs.  They share memory space with the program that created them.  
  589.  
  590. OS/2 supports thread creation and management through the functions 
  591. DosCreateThread, DosKillThread, DosResumeThread, DosSuspendThread, and
  592. DosWaitThread.  
  593.  
  594. To load thread support into Forth/2, issue the command
  595.  
  596.     INCLUDE" THREADS.4TH"
  597.  
  598. in your  STARTUP.4TH  file, which should itself be INCLUDE"ed in 
  599. FORTH.INI.
  600.  
  601.  
  602. 3.4.1  Creating Threads and USER Variables
  603.  
  604. In Forth/2 a thread can be created to perform some action in the 
  605. background, and free up the main program for other uses.  For example, 
  606. you may want to start a separate thread to load a large table of numbers 
  607. into memory and perform computations.  Or, a thread can simply put 
  608. itself to sleep and wake up at hourly intervals to perform some 
  609. function.  
  610.  
  611. Most self-contained words in Forth/2 can be performed as a separate
  612. thread.  When the thread starts, it is given its own stack, and its own 
  613. copies of USER variables.  
  614.  
  615. USER variables are variables which multiple threads may use without
  616. interfering with each other.  For example, if you define a variable X1,
  617. but two different threads use this variable, then problems may arise.
  618. One thread may store into the value, only to have the intended value
  619. overwritten by another thread.
  620.  
  621. If X1 was created as a USER variable, however, then although the code for
  622. each thread uses a USER variable called X1, they will be in entirely 
  623. different locations and will not interfere with each other.  This allows
  624. you to create what is commonly referred to as reentrant code.
  625.  
  626. A good example is variables which hold file handles, file pointers, etc.  
  627. Without USER variables, if two threads tried to read or write files at
  628. the same time, the handles and pointers would overwrite each other.  You 
  629. would need two separate words which use different sets of variables in 
  630. order to get just two threads to do the same function at the same time.  
  631.  
  632. With USER variables, when the thread is created it is given a copy of
  633. the current USER variables.  After that, can freely modify them,
  634. while using the exact same Forth words that other threads use.
  635.  
  636.  
  637. In many cases, you may want to share a variable between threads.  For
  638. example, you may want to create a "watchdog" thread which continually
  639. examines a variable for a certain number.  This is a great help in
  640. debugging programs.
  641.  
  642.     variable XV1
  643.     : WatchDog  begin  XV1 @ 0< IF  CR ." XV1 < 0 !"  1 sleep  then
  644.                        100 usleep
  645.                 0 until ;
  646.  
  647. To run this as a separate thread, simply type
  648.  
  649.     Thread WatchDog
  650.  
  651. and test it by storing different values into XV1.  The  1 sleep  is
  652. there to prevent a huge number of warning messages, and the 100 usleep
  653. is there to prevent the thread from slowing down the system too much.
  654.  
  655.  
  656.  
  657. 3.4.2  Exiting and Terminating Threads
  658.  
  659. When Forth/2 is exited via BYE, all threads created by it will also be 
  660. terminated.  (This may be controlled by an option in an upcoming version
  661. of Forth/2).  If you wish to kill separate threads, use the ThreadID
  662. variable to obtain the identification number of the most recently 
  663. created thread, and type
  664.  
  665.     ThreadID @ KillThread
  666.  
  667. Look at the examples in the  THREADS.4TH  file for two other examples of
  668. using threads.  If the word, such as Timer, finishes executing and
  669. gets to the  ;  then the thread will terminate itself.  The thread may
  670. also use  BYE  and  EXIT  to terminate before the  ;
  671.  
  672.  
  673.  
  674. 3.4.3  Using ABORT in Threads
  675.  
  676. The word  ABORT  is vectored through  'ABORT.  In effect, ABORT is
  677.  
  678.     : ABORT  ( -- )  'ABORT @ EXECUTE ;
  679.  
  680. If your thread calls  ABORT  or  ABORT"  you may want to redirect ABORT to
  681. terminate the thread.  If you do not, it will halt the main program from
  682. doing whatever it is doing.  To redirect  ABORT  do the following:
  683.  
  684.     : ThreadAbort   ' BYE  CFA @  'ABORT ! ;
  685.  
  686. Then, simply call  ThreadAbort  in the beginning of the code for the
  687. thread.  When  ABORT  is called from the thread, the thread will 
  688. gracefully terminate.
  689.  
  690.  
  691.  
  692. 3.4.4  The USER Variable Area
  693.  
  694. Currently, a number of system variables such as BASE, the dictionary 
  695. pointer, STATE, et al., are not USER variables yet.  (It requires some 
  696. slight changes in how things are coded:  see Part 5 for details).  
  697.  
  698. Consequently, threads cannot request input from the terminal (although 
  699. they may send harmless output to the screen), nor can they compile new
  700. definitions.  These limitations may change in a future release.  
  701.  
  702. If you wish to initialize a thread with a different default USER 
  703. variable area other than the current thread's area, then store the 
  704. address of the new default area into the variable  'USER.  The size of
  705. the USER area is  UDP @  USER0 -  where  UDP  is the USER area free
  706. memory pointer, and  USER0  is the current thread's USER variable base.
  707.  
  708.  
  709.  
  710.  
  711. 3.5  ARRAYS AND STRUCTURES
  712.  
  713. Arrays and structures are supported in the file  STRUCT.4TH which you
  714. can load via  INCLUDE" STRUCT.4TH"
  715.  
  716. Structures hold groups of various information, such as a transaction 
  717. which has an identification number, a time/date stamp, a text 
  718. description, codes, and various other parameters.  A structure brings 
  719. all of this information into one convenient element which can be easily 
  720. manipulated.  
  721.  
  722. <<See the file  STRUCT.4TH  for more information and examples.>>
  723.  
  724.  
  725.  
  726. 3.6  VOCABULARIES
  727.  
  728. Vocabularies under Forth/2 work like most other Forths.  To create a 
  729. vocabulary to hold a group of words, use
  730.  
  731.     VOCABULARY <vocabulary_name>
  732.  
  733. In order to tell Forth which vocabulary you wish to add new colon 
  734. definitions, variables, constants, etc. to, use
  735.  
  736.     <vocabulary_name> DEFINITIONS
  737.  
  738. Two vocabularies are already defined,  FORTH  and  SYSTEM.  When you 
  739. use the command WORDS to list the current Forth words, you will see the
  740. Forth vocabulary and possibly other vocabularies as well.  To only show 
  741. the FORTH vocabulary, simply type 
  742.  
  743.     Forth ONLY
  744.  
  745. Then,  WORDS  will show only the definitions in the Forth vocabulary.
  746. To see the SYSTEM vocabulary, simply type 
  747.  
  748.     SYSTEM WORDS
  749.  
  750. and you will see the system vocabulary, followed by the Forth 
  751. vocabulary.  Then, type FORTH words and you will instead see the Forth 
  752. vocabulary first, followed by the system vocabulary.  
  753.  
  754. Forth/2 keeps track of a  CURRENT  vocabulary, where all new definitions
  755. are added, as well as a list of  CONTEXT  vocabularies.  CONTEXT vocab-
  756. ularies are where Forth searches to find a word, either to execute it or
  757. to compile it.  What you see in the WORDS listing is the same order that 
  758. Forth/2 will use to search for words when compiling.  
  759.  
  760. Whenever you invoke the name of a vocabulary, if it is already in 
  761. CONTEXT  then it will simply be moved into the top of the search order.
  762. If it is not already in  CONTEXT, then it will be added to the top of 
  763. the search order.  
  764.  
  765. To create two vocabularies, then define the search order for the words 
  766. as Voc2 first, then Voc1, then Voc3, then System, then Forth, do the 
  767. following:  
  768.  
  769.     VOCABULARY Voc1     : XV1  ... ;   : XV2   ... ;
  770.     VOCABULARY Voc2     : XV3  ... ;   : XV4   ... ;
  771.     VOCABULARY Voc3     : XV1  ... ;   : XV2   ... ;
  772.  
  773.     Forth ONLY
  774.     Forth System Voc3 Voc1 Voc2 DEFINITIONS
  775.  
  776. New words will be added to Voc2.  In the example above, the same word
  777. XV1 is defined in both vocabularies Voc1 and Voc3.  In this case, 
  778. because of the search order defined, if  XV1  is invoked, then the XV1
  779. from Voc1 will be executed, even though the  XV1  from Voc3 was defined
  780. later.  
  781.  
  782. The  Forth ONLY  above clears out any other unwanted vocabularies.
  783.  
  784.  
  785.  
  786. 3.7  LOCAL VARIABLES
  787.  
  788. Local variables enhance Forth by reducing the complexity of stack 
  789. operations, and allow you to assign descriptive labels to the numbers 
  790. passed to the word on the stack.
  791.  
  792. Local variables are supported in the file called  LOCALS.4TH.  Use 
  793. INCLUDE" LOCALS.4TH" in STARTUP.4TH to load local variable support every
  794. time Forth/2 is started.
  795.  
  796. If you pass three parameters to a word, perhaps ( addr len dest -- )
  797. and want to copy addr,len to the dest address, you could label these 
  798. parameters as:
  799.  
  800.     LOCALS| addr len dest |
  801.  
  802. After that, you are free to use the words  addr, len, and dest just as 
  803. if they were regular Forth words.  When the word containing the LOCALS|
  804. is executed, at the point  LOCALS|  appears the top three numbers on the
  805. stack are saved into a special data area, and the numbers are dropped 
  806. off the stack.  When  addr  gets executed, it fetches the value of the
  807. thrid element in the locals data area, and pushes it onto the stack.
  808.  
  809. The general format of this is as follows:
  810.  
  811. : WordName  LOCALS|  local1  local2  local3  ...  local8 |
  812.                      ...  local1  ...
  813.                      ...  local2  ...  local3  ... etc.  ;
  814.  
  815. The entire  LOCALS| ... |  must be on the same line.
  816.  
  817. One simple example is below:
  818.  
  819.    : DIGITS    LOCALS|  digit1 digit2 digit3 |
  820.                         digit1  100 *
  821.                         digit2   10 *
  822.                         digit3  + + ;
  823.  
  824. DIGITS  turns  1 2 3 DIGITS  into  123
  825.  
  826.  
  827. In regular Forth you would need code like this to do the same thing:
  828.  
  829. : DIGITS       ROT  100 *   ROT  10 *  + + ;
  830.  
  831. It is much less clear what the second version of DIGITS does.
  832.  
  833. LOCAL's are somewhat slower than regular Forth words, although this may 
  834. be changed if some words are turned into assembly words.  
  835.  
  836.  
  837.  
  838.  
  839. 4.  DESCRIPTION OF WORDS
  840.  
  841. This is an incomplete list of the words included in Forth/2.  Some are
  842. included in the FORTH.EXE file, others are in the FORTH.INI file.
  843.  
  844.  
  845. 4.1  Parameters
  846.  
  847. The parameters each Forth word requires, and the parameters it returns
  848. are specified by the following convention:  
  849.  
  850.     ( n1 n2 n3 ... -- r1 r2 r2 ... )
  851.  
  852. where n1, n2, n3, etc.  are the required parameters, and r1, r2, r3, 
  853. etc.  are the results.  For example, the word DUP duplicates the top 
  854. number on the stack, so it has the stack definition:  
  855.  
  856. DUP       ( n -- n n )  Duplicates the number on top of the stack
  857.  
  858. The word ?DUP duplicates the number on the stack if it is non-zero.  It
  859. returns different numbers of parameters depending on the top of stack:
  860.  
  861. ?DUP ( n -- n 1 -- 0 )  DUPlicates n if non-zero.
  862.  
  863. The word ' (tick) fetches the address of the following word, e.g.  ' DUP 
  864. will return the starting address of the DUP definition header, the Link 
  865. Field Address (LFA).  
  866.  
  867. '       ( word-- LFA )  gets the LFA address of the following word
  868.  
  869. So, when something is right up against the --'s, it expects a word or 
  870. set of words from the input stream.  
  871.  
  872.  
  873.  
  874. 4.2  Parameter Naming Conventions
  875.  
  876. Some naming conventions for the parameters are:
  877.  
  878. addr     a 32-bit address (or just 'a')
  879. b        an 8-bit byte
  880. char     an ASCII character
  881. n        a 32-bit number
  882. "        the address of a string
  883. ?        the number of parameters is unknown
  884.  
  885.  
  886.  
  887. 4.3  List of Word Definitions (INCOMPLETE)
  888.  
  889. --Begin--
  890. !        ( n addr -- )  Stores the number n into address addr
  891. "       ( word" -- a )  Returns the addr of the counted string ending in "
  892. "CAT   ( addr1 addr2 )  ConCATenates counted string at addr1 to end of addr2
  893. "CONSTANT     ( " -- )  Creates a string constant  Does> ( -- a )
  894. "MOVE  ( addr1 addr2 )  Copies counted string from addr1 to addr1
  895. #OUT       ( -- addr )  Variable holding # of characters written to line
  896. #TIB          ( -- n )  Address of the current offset in the TIB
  897. '       ( word-- LFA )  Gets the LFA address of the following word
  898. 'ABORT     ( -- addr )  Pointer to code to execute when ABORT is called
  899. 'USER      ( -- addr )  Pointer to the default USER area for new threads
  900. (               ( -- )  Skips interpreting words up to the next )
  901. *   ( n1 n2 -- n1*n2 )  Multiplies numbers on top of the stack
  902. */      ( a b c -- d )  Calculates  d = a * b/c  i.e. mutliply by ratio
  903. */MOD ( a b c -- r d )  Calculates  d = a * b/c  r=remainder
  904. +   ( n1 n2 -- n1+n2 )  Adds the two numbers on top of the stack
  905. +!       ( n addr -- )  Adds n to contents of addr
  906. +LOOP         ( n -- )  Adds n to loop counter and loops back
  907. +TO             ( -- )  Sets flag for adding value into integer:  1 +TO X1
  908. ,             ( n -- )  Stores n at dictionary pointer, increments DP by 4
  909. -   ( n1 n2 -- n1-n2 )  Subtracts numbers on top of the stack
  910. -ROT ( a b c - c a b )  Rotates top of stack to the third position
  911. -TRAILING ( a n1 -- a n2 )  Truncates extra spaces at end of string at a[ddr]
  912. .             ( n -- )  Prints the value of the top number on the stack
  913. ."      ( <string>== )  Prints a string up to the first "
  914. .(      ( <string>-- )  Prints a string up to the first )
  915. .S              ( -- )  Prints the contents of the stack non-destructively
  916. /   ( n1 n2 -- n1/n2 )  Divides numbers on top of the stack
  917. /MOD ( n1 n2 - n3 n4 )  Divides n1/n2, n3=remainder, n4=quotient
  918. 0"      ( word" -- n )  Returns the addr of the 0-terminated string ending in "
  919. 0"COUNT ( a -- a len )  Returns address and length of the 0-terminated string
  920. 2CONSTANT ( n1 n2 name ) Creates a two-number constant: 100 0 2CONSTANT CNTDWN
  921. 2DROP     ( n1 n2 -- )  Drops two numbers from the stack
  922. 2DUP ( n1 n2 -- n1 n2 n1 n2 )  Duplicates the double number on the stack
  923. :               ( -- )  Creates a new word to perform the words up to the ;
  924. ;               ( -- )  Marks the end of a definition
  925. <       ( n1 n2 -- f )  True if n1 < n2
  926. <<     ( n1 n2 -- n3 )  Shifts n1 by n2 bits left,  e.g. 100 5 << = 100 2^5 *
  927. ="      ( a1 a2 -- f )  True if counted strings at a1 and a2 equal. See STRING"
  928. =STRING ( a1 len a2 -- f ) True if string at a1,len equal to counted string a2
  929. >       ( n1 n2 -- f )  True if n1 > n2
  930. >>     ( n1 n2 -- n3 )  Shifts n1 by n2 bits right, e.g. 100 3 >> = 100 2^3 /
  931. >IN        ( -- addr )  Variable holding number of bytes left in input line
  932. >R            ( n -- )  Pushes number onto return stack.  Use in pairs with R>
  933. ?COMPILE        ( -- )  Gives error if not called in compile mode
  934. ?CR           ( -- f )  Does a CR if #OUT is greater than 64
  935. ?DUP ( n -- n 1 -- 0 )  DUPlicates n if non-zero. Eliminates an ELSE DROP THEN
  936. ?STACK          ( -- )  Gives error if the stack is out of bounds
  937. @        ( addr -- n )  Replaces address addr with it's contents
  938. @+    ( a -- a+4 [a] )  Returns address a+4 and contents of a.  See COUNT
  939. ABORT           ( -- )  Halts execution and returns to the Forth command line
  940. ABORT"        ( f -- )  If true shows an error msg ending in " and calls ABORT
  941. ABS       ( n -- |n| )  Calculates absolute value
  942. ALLOT         ( n -- )  Allocates storage space after VARIABLE or CREATE
  943. ALONG ( a b -- a+b a )  Use before DO when you have an address and length
  944. AND    ( n1 n2 -- n3 )  Returns the bit-wise AND of  n3 = n1 AND n2
  945. ARGS"   ( arguments" )  Passes arguments to the SHELL" :  ARGS" FILE.TXT"
  946. ASCII       ( char-- )  Returns ASCII value of character:  ASCII A
  947. BASE       ( -- addr )  Variable holding base for number conversion
  948. BL            ( -- c )  ASCII character for a blank space, 32
  949. BYE             ( -- )  Terminates current process (BYE == Leave forth)
  950. C!          ( b n -- )  Stores  byte at address n
  951. C,            ( b -- )  Compiles a byte into the dictionary
  952. C@          ( n -- b )  Fetches byte at address n
  953. CALL" ( <string><word> )  Creates a string constant, CALL" Clinton" President
  954. CMOVE ( a1 a2 len -- )  Moves len bytes from address a1 to address a2
  955. CMOVE> ( a1 a2 len - )  Moves len bytes from a a1 to a2, high memory first
  956. COMMANDLINE( -- addr )  Returns the linear address of the command line
  957. CommandShell    ( -- )  Temporarily exits to the OS/2 command line
  958. COMPILE         ( -- )  Postpones compilation of the following word
  959. COMPILECALL ( adr -- )  Compiles a call to the address given
  960. CONSTANT ( n word -- )  Creates the constant <word> which represents n
  961. CONTEXT    ( -- addr )  Address of CONTEXT, list of vocabularies to search
  962. COUNT ( a -- a+1 [a] )  Returns the address+1 and the byte at addr
  963. CR              ( -- )  Outputs a carriage return and line feed.
  964. CREATE      ( word-- )  Creates a word which returns its address when called
  965. CURRENT    ( -- addr )  Pointer to vocabulary where new words are added
  966. D>F         ( n -- R )  Converts the top stack entry to a Real
  967. DECIMAL         ( -- )  Start entering and printing all decimal numbers
  968. DEFINITIONS     ( -- )  Sets the vocabulary where new words are created
  969. DEPTH         ( -- n )  Number of elements on stack
  970. DO        ( n2 n1 -- )  Repeats from n1 up to n2.  Use with LOOP
  971. DOES>           ( -- )  Used after CREATE to define run-time action of word
  972. DP!           ( n -- )  Sets the dictionary pointer to a new value: DP !
  973. DPL        ( -- addr )  Variable holding decimal point location from NUMBER?
  974. DROP          ( n -- )  Drops the top number from the stack
  975. DROPS         ( n -- )  Drops n words from the stack
  976. DUMP   ( addr len -- )  Shows contents of a range of memory
  977. DumpRegisters   ( -- )  Shows the current contents of the CPU registers
  978. DUP       ( n -- n n )  Duplicates the number on top of the stack
  979. ECHO       ( -- addr )  Use ECHO ON or ECHO OFF to echo the file being loading
  980. ELSE            ( -- )  Executes following words when IF condition false
  981. EMIT       ( char -- )  Outputs an ASCII character
  982. ENVIRONMENT( -- addr )  Returns the linear address of the Environment Space
  983. EOF?          ( -- f )  True if at the end of file read with FRead
  984. EXECUTE    ( addr -- )  Executes the code at address, ' .S CFA @ EXECUTE
  985. EXITCODE   ( -- addr )  Variable holding exit code returned to OS/2 after BYE
  986. F!       ( R addr -- )  Stores a Real at memory address
  987. F*  ( R1 R2 -- R1*R2 )  Multiplies the two numbers on the floating point stack
  988. F+  ( R1 R2 -- R1+R2 )  Adds the two numbers on the floating point stack
  989. F-  ( R1 R2 -- R1-R2 )  Subtracts R2 from R1
  990. F.            ( R -- )  Prints and consumes, the top floating point number
  991. F/  ( R1 R2 -- R1/R2 )  Divides R1 by R2
  992. F0<         ( R -- f )  True if R < 0.0
  993. F0=         ( R -- f )  True if R = 0.0
  994. F<      ( R1 R2 -- f )  True if R2 < R1
  995. F>D         ( R -- n )  Converts the top Real to a Number
  996. F@       ( addr -- R )  Reads a Real from an address
  997. FABS        ( R -- R )  Returns the ABSOLUTE value of the stack top
  998. FALIGN          ( -- )  Assures that the next allot will be float aligned
  999. FALIGNED (addr -- f-addr) f-addr is the first f-alligned address >= addr
  1000. FALSE         ( -- 0 )  Returns the constant FALSE = 0
  1001. FBUFFER    ( -- addr )  Address of a 16K buffer for loading files
  1002. FCLEAR          ( -- )  Initializes the Floating Point Stack
  1003. FCONSTANT   ( R word )  Creates the constant <word> which represents R
  1004. FCOS    ( R -- Cos<r>)  Returns the Consine of angle R in radians
  1005. FDEPTH        ( -- n )  Returns the depth of the floating point stack
  1006. FDROP         ( R -- )  Drops the top floating point entry
  1007. FDUP       ( R - R R )  Duplicates the top floating point entry
  1008. FENCE      ( -- addr )  Sets lowest point to which you can FORGET words
  1009. FILL   ( addr n b -- )  Fills n bytes at addr with byte b
  1010. FLOOR       ( R -- R )  Truncates R towards -infinity
  1011. FOR       ( n2 n1 -- )  Repeats from n1 to n2 if n2>n1.  Use with NEXT
  1012. FORGET      ( word-- )  Forgets all words up to and including the word
  1013. FROUND      ( R -- R )  Rounds to nearest integer
  1014. FSEEK   ( h ptr -- f )  Sets file handle h's position to ptr, f=0 successful
  1015. FSIN    ( R -- Sin<r>)  Returns the Sine of angle R in radians
  1016. FSINCOS ( R -- Sin<r> Cos<r>) Returns sine and consine of angle R in radians
  1017. FSQRT ( R -- Sqrt<r> )  Returns the square root of R
  1018. FSWAP (R1 R2 -- R2 R1)  Swaps the two reals on the stack
  1019. FVARIABLE ( <name>-- )  Creates a REAL variable called <name>
  1020. HERE          ( -- n )  Returns dictionary pointer
  1021. HEX             ( -- )  Start entering and printing all hexadecimal numbers
  1022. I             ( -- n )  Current LOOP value of innermost LOOP
  1023. IF            ( f -- )  Executes the following words if flag f is non-zero
  1024. IMMEDIATE       ( -- )  Marks last word defined as IMMEDIATE.
  1025. INCLUDE       ( " -- )  Loads and compiles the file name given at the address
  1026. INCLUDE"   ( file"-- )  Loads and compiles the file name ending with a "
  1027. INTEGER    ( word -- )  Creates an integer which returns it's value. See TO +TO
  1028. J             ( -- n )  Current LOOP value of second nested LOOP
  1029. K             ( -- n )  Current LOOP value of third  nested LOOP
  1030. KEY           ( -- b )  Waits for a key to be received, returns ASCII value
  1031. KEYNOWAIT     ( -- n )  Returns the raw keyboard scan code: 27=no key
  1032. LAST       ( -- addr )  Address containing pointer to last word defined
  1033. LEAVE           ( -- )  Causes DO...LOOP to terminate at next LOOP
  1034. LITERAL         ( -- )  Compiles a literal number into word: [ 100 ] LITERAL
  1035. LOCALS|       ( ? -- )  Defines local variables:  LOCALS| a b c |  ...
  1036. LOOP            ( -- )  Branches back to  DO
  1037. MAX    ( n1 n2 -- n3 )  Returns the greater of n1 and n2
  1038. MIN    ( n1 n2 -- n3 )  Returns the lesser  of n1 and n2
  1039. MOD    ( n1 n2 -- n3 )  Returns n1 modulo n2 (i.e. the remainder)
  1040. MORE" ( <filename>-- )  Types the contents of a text file: MORE" THREADS.4TH"
  1041. MOVE>" ( a len a2 -- )  Moves string at address a,len to counted string at a2
  1042. MS            ( n -- )  Suspends the current thread for at least n milliseconds
  1043. NDROP         ( n -- )  Drops n elements off the stack
  1044. NEGATE     ( n -- -n )  Multiplies n by -1
  1045. NEXT            ( -- )  Loops back to FOR
  1046. NIP    ( n1 n2 -- n2 )  Removes the second number from the stack
  1047. NUMBER? ( " -- n 1 -- 0 ) Converts string to number: true if success else false
  1048. OFF        ( addr -- )  Stores a FALSE at the address
  1049. ON         ( addr -- )  Stores a TRUE  at the address
  1050. ONLY            ( -- )  Makes the most recently cited vocabulary the only one
  1051. OPEN       ( 0" -- h )  Opens the 0-terminated file name and returns handle
  1052. OR     ( n1 n2 -- n3 )  Returns the bit-wise OR of  n3 = n1 OR n2
  1053. OUT        ( -- addr )  Address of variable holding output cursor position
  1054. OVER  ( a b -- a b a )  Copies the second number to the top of the stack
  1055. PAD        ( -- addr )  Address of scratch-pad memory
  1056. PI            ( -- R )  Returns the constant PI 3.1415926....
  1057. PICK      ( ? i -- ? )  Copies the i'th element on the stack to the top
  1058. QUIT            ( -- )  Quits execution and returns to Forth command line
  1059. R>            ( -- n )  Pops number from return stack.  Used with >R
  1060. R@            ( -- n )  Copy number from top of return stack
  1061. READLN  ( h -- a len )  Reads next line of input from file h, then try TYPE
  1062. RECURSE         ( -- )  Compiles a recursive call to the definition itself
  1063. ROLL      ( ? i -- ? )  Rolls the i'th element on the stack to the top
  1064. ROT ( a b c -- b c a )  Rotates third element to top of stack
  1065. SHELL"  ( string" -- )  Runs the given program:  SHELL" EDITOR.EXE" See ARGS"
  1066. SP!        ( addr -- )  Sets stack pointer to address.  SP0 SP! to clear stack
  1067. SP0        ( -- addr )  Base address of the stack
  1068. SP@        ( -- addr )  Stack pointer address
  1069. SPACE           ( -- )  Outputs a space
  1070. SPAN          ( -- n )  Address of the current offset in the TIB (same as #TIB)
  1071. STATE      ( -- addr )  Address of variable holding compilation state
  1072. STRING    ( <name>-- )  Creates a TO variable string: STRING S1  " YES" TO S1
  1073. SWAP    ( a b -- b a )  Swaps the two numbers on the stack
  1074. SYSCALL ( ? sys$ -- ? )  Calls a system routine starting with SYS$
  1075. THEN            ( -- )  Marks the end of an IF .. THEN  or IF .. ELSE .. THEN
  1076. THREAD   ( <word> -- )  Starts a thread to execute <word>: THREAD Bunny
  1077. TIB           ( -- n )  A variable holding a pointer to the Terminal Input Buf.
  1078. TO              ( -- )  Sets flag for storing value into integer, e.g. 1 TO X1
  1079. TOGGLE   ( n addr -- )  Toggles bits n at word address addr
  1080. TONE   ( freq dur -- )  Emits a tone for a given frequency(Hz) and duration(ms)
  1081. TRUE         ( -- -1 )  Returns the constant TRUE = -1
  1082. TUCK ( n1 n2 -- n2 n1 n2 )  Makes a copy of n2 under n1
  1083. TYPE     ( addr n -- )  Types out the n characters at address addr
  1084. U*     ( n1 n2 -- n3 )  Unsigned multiply  n3 = n1 * n2
  1085. U*/MOD ( a b c - r d )  Unsigned  d = a * b/c  r=remainder
  1086. U.            ( n -- )  Prints the unsigned value of the number
  1087. U/     ( n1 n2 -- n3 )  Unsigned divide,   n3 = n1 / n2
  1088. UALLOT        ( n -- )  Allot n words of USER variable space
  1089. UDP        ( -- addr )  Address of USER variable pointer
  1090. USER      ( <name>-- )  Creates a USER variable called <name>
  1091. USER0      ( -- addr )  Address of beginning of USER varaible area
  1092. VARIABLE  ( <name>-- )  Creates a variable called <name>
  1093. VIEW      ( <name>-- )  Views the description for a word.  VIEW VIEW
  1094. VOCABULARY ( <name>- )  Creates a new vocabulary: VOCABULARY VOC1
  1095. W             ( -- 4 )  Word size for addresses, variables, etc.  Also CELL
  1096. W!     ( addr 16b -- )  Stores  the 16-bit word at addr.  DO NOT CONFUSE WITH W
  1097. W*        ( n -- n*4 )  Multiplies by the word size 4.            Also CELLS
  1098. W+        ( n -- n+4 )  Adds the word size 4.                     Also CELL+
  1099. W-        ( n -- n-4 )  Subtracts the word size 4.                Also CELL-
  1100. W@     ( addr -- 16b )  Fetches the 16-bit word at addr.  DO NOT CONFUSE WITH W
  1101. WORD ( char string-- a )  Parse string delimited by char, return counted string
  1102. WORDS           ( -- )  Shows the forth words in CONTEXT
  1103. XOR    ( n1 n2 -- n3 )  Returns the bit-wise exclusive-OR of  n3 = n1 XOR n2
  1104. XY          ( x y -- )  Move cursor to screen location (x,y)=(col,row)
  1105. [               ( -- )  Stops   compilation in : definitions
  1106. [COMPILE]       ( -- )  Compiles the following immediate word into definition
  1107. \               ( -- )  Signals that the rest of the line is a comment
  1108. ]               ( -- )  Resumes compilation in : definitions
  1109.  
  1110. STRINGS  String words:  WORD  "   ="  "CAT  "MOVE   MOVE>"  =STRING  STRING
  1111.  
  1112.  
  1113.  
  1114. 5.  TECHNICAL DESCRIPTION
  1115.  
  1116. 5.1  Internals
  1117.  
  1118. Forth/2 is a direct, subroutine threaded Forth.  Colon definitions are 
  1119. made up of a series of 32-bit relative calls to other words.  The opcode 
  1120. for these calls is E8h, followed by a four-byte offset to the code.  
  1121.  
  1122. The return stack pointer (RP) is the ESP register.
  1123. The   user stack pointer (SP) is the EBX register and grows downward.
  1124. The   user area  pointer (UP) is the EBP register.
  1125. There is no need for an instruction pointer (IP).
  1126.  
  1127. So, a DUP instruction would be coded this way in MASM:
  1128.              mov       eax,[ebx]
  1129.              sub       ebx,4
  1130.              mov       [ebx],eax
  1131.              ret
  1132.  
  1133. DO...LOOP's are created as in-line code, thereby maximizing performance.
  1134. Literal numbers are also coded in-line.  They would take up 9 bytes to
  1135. code using the more traditional call to LIT, followed by the literal.
  1136. However, in only ten bytes it can be done much more quickly using
  1137. in-line code.
  1138.  
  1139. Currently, Forth/2 is case insensitive.  All defined words are converted 
  1140. to upper-case before being entered into the dictionary.  Forth words can 
  1141. be entered in any mix of upper and lower case, they are all the same.  
  1142.  
  1143. All math words like * / + - etc.  are fully 32-bit.  In addtion, the 
  1144. words */ and */MOD use 32-bit arguments but do generate 64-bit 
  1145. intermediate results.  No 64-bit double-number words such as D+, M*, or 
  1146. UM/MOD have been defined.  
  1147.  
  1148.  
  1149.  
  1150. 5.2  OS/2 Interface
  1151.  
  1152. OS/2 32-bit system calls are implemented by saving most registers, 
  1153. saving the ESP in EBP, setting ESP to EBX, calling the system routine,
  1154. then restoring ESP and the other registers.  Basically, this switches 
  1155. the stacks so that the parameters passed to OS/2 calls do not need to be
  1156. shuffled around.  The function which makes the system call must drop all 
  1157. the parameters it put on, as OS/2 does not do this (just as in C).  
  1158.  
  1159. To call OS/2 system functions, you must use the word SYSCALL which 
  1160. requires the address of the system call on the top of the stack.  Words
  1161. such as SYS$BEEP, SYS$READ, SYS$WRITE, SYS$OPEN et.  al.  return the 
  1162. addresses corresponding to the OS/2 functions DosBeep, DosRead, 
  1163. DosWrite, DosOpen, etc.  All use 32-bit arguments.  
  1164.  
  1165. The function calls are kept in a separate vocabulary called SYSTEM.  
  1166. Before you use any of these system calls, make sure SYSTEM gets executed 
  1167. to put the vocabulary into CONTEXT so that these calls will be visible.  
  1168.  
  1169. To translate OS/2 documentation, usually given with C calling 
  1170. conventions, into equivalent Forth/2 code, remember that in C the 
  1171. parameters are pushed onto the stack from right to left.  For the 
  1172. function DosBeep, the OS/2 Technical Library lists the function this 
  1173. way:
  1174.  
  1175.     APIRET DosBeep (ULONG ulFrequency, ULONG ulDuration)
  1176.  
  1177. To call this from Forth, do the following:
  1178.  
  1179.     Duration @  Frequency @  SYS$BEEP  SYSCALL  3 DROPS
  1180.  
  1181. You must drop all parameters after each SYSCALL.
  1182.  
  1183.  
  1184. To pass pointers to OS/2 functions, simply use the names of the 
  1185. variables, which place their address on the stack.  DosGetDateTime is 
  1186. listed as:  
  1187.  
  1188.     APIRET DosGetDateTime (PDATETIME ppPDateTime)
  1189.  
  1190. so call it as follows:
  1191.  
  1192.     VARIABLE DateTime   7 ALLOT  ( DateTime structure is 11 bytes long )
  1193.  
  1194.     DateTime SYS$GetDateTime SYSCALL  2DROP
  1195.  
  1196. The ASCII characters representing the date and time will be stored in 
  1197. the memory structure at DateTime.
  1198.  
  1199.  
  1200.  
  1201. 5.3  USER Variables and Multi-Tasking
  1202.  
  1203.  
  1204.  
  1205. 5.4  TO Variables (VALUE's)
  1206.  
  1207. TO variables use a system variable called  %TO  to determine if they should
  1208. return their value, or store or add into the variable.  If %TO is zero, the
  1209. variables return their value.  If %TO is >0, the number on top of the stack
  1210. is stored into the variable.   If %TO is <0, the number on top of the stack
  1211. is added to the variable.  The following words, defined in assembly for
  1212. speed but reproduced here, show how this works.
  1213.  
  1214.     VARIABLE %TO
  1215.     : TO    1 %TO ! ;
  1216.     : +TO  -1 %TO ! ;
  1217.     : <TODOES> ( addr -- ? )  %TO @ 0 = IF  @  ELSE
  1218.                               %TO @ 0 > IF  !  ELSE  +!  THEN THEN
  1219.                               0 %TO ! ;
  1220.  
  1221.     : INTEGER ( -- )  CREATE  0 ,   DOES>  <TODOES> ;
  1222.  
  1223. This can be augmented to accept initial values when the INTEGER is created.
  1224.  
  1225.     : INTEGER ( -- )  CREATE  HERE  0 ,
  1226.                               %TO @ IF  <TODOES>  ELSE  DROP  THEN
  1227.                       DOES>   <TODOES> ;
  1228.  
  1229. To store an initial value into the first version of INTEGER, you must do:
  1230.  
  1231.     INTEGER X  100 TO X
  1232.  
  1233. whereas with the second version you can combine these as:
  1234.  
  1235.     100 TO INTEGER X
  1236.  
  1237.  
  1238.  
  1239. 5.5  VOCABULARIES
  1240.  
  1241. Vocabulary structures are made up of three words:
  1242.  
  1243.     1   0          Unused
  1244.     2   VocPtr     Pointer to the last Forth word created in this vocabulary
  1245.     3   Voc-Link   Link to most recently created vocabulary
  1246.  
  1247. The word  VOC-LINK  is the head of a linked-list of vocabularies in the
  1248. order in which they were created.  VOC-LINK is needed in order to
  1249. FORGET words across multiple vocabularies.
  1250.  
  1251. When created, each vocabulary VocPtr is set to zero.  That way, all
  1252. vocabularies chain back to 0, not any other vocabularies.  To search
  1253. multiple vocabularies, each vocabulary name must be executed to
  1254. have it insert itself into the list of vocabularies in CONTEXT.
  1255.  
  1256.  
  1257.  
  1258. 5.6  Specifications and Limits
  1259.  
  1260. The following limits are present in the current Forth/2 system.  Since this
  1261. is a 32-bit Forth using a flat, non-segmented address space, most of these
  1262. limits are arbitrary and are simply controlled by constants in the compiler.
  1263.  
  1264. Word size:                                          4 Bytes  (32 bits)
  1265. Word name length maximum size:                     31 Bytes
  1266. Base code (.EXE) size:                           35 K Bytes  (So far)
  1267. FORTH.INI code size:                             14 K Bytes  (So far)
  1268.  
  1269. Dictionary size limit (incl. FORTH.INI):         64 K Bytes
  1270. User stack size limit:                            4 K Bytes  (1024 elements)
  1271. User stack underflow size limit:                  4 K Bytes  (1024 elements)
  1272. Return stack size limit:                          8 K Bytes* (2048 elements)
  1273. Return stack underflow size limit:                0 K Bytes
  1274. USER variable area size limit:                    4 K Bytes
  1275. File Buffer Size limit:                          16 K Bytes  (for FORTH.INI)
  1276. Terminal Input Buffer (TIB) Size limit:           256 Bytes
  1277.  
  1278. Terminal I/O:                                    ANSI compatibility
  1279. Alphabetic case sensitivity:                     Case insensitive (Dup==DUP)
  1280.  
  1281.  
  1282. * Note:  The return stack is handled by OS/2 using a guard-page technique.
  1283.          If the stack grows past 4K, a new 4K Byte page is allocated.
  1284.          Forth/2 will allow up to 1 one more page to be allocated.
  1285.  
  1286.  
  1287.  
  1288.  
  1289. 6.  COMPATIBILITY
  1290.  
  1291. There are some differences in the way this Forth works compared to most
  1292. other Forths.  Some of these may be changed in a future version.
  1293.  
  1294.  
  1295. 6.1  Compatibility with Forth-83
  1296.  
  1297. Since this Forth is still in development, not all words are supported
  1298. yet.  The following words from the Forth-83 Standard have not been
  1299. created yet in Forth/2:
  1300.  
  1301.   >BODY  CONVERT
  1302.   D+  D<  DNEGATE  UM*  UM/MOD
  1303.  
  1304. In the file BLOCKS.4TH which accompanies Forth/2 are some preliminary
  1305. words which can read and load block files.  However, multiple buffers
  1306. and the ability to save those blocks back to disk has not been imp-
  1307. lemented.  It is recommended that you use the conversion utility to
  1308. convert your block files into sequential files.
  1309.  
  1310. The following words are therefore only partially supported:
  1311.  
  1312.   BLK  BLOCK  BUFFER  FLUSH  LOAD  SAVE-BUFFERS  UPDATE
  1313.  
  1314.  
  1315.  
  1316.  
  1317. 6.2  Compatibility issues with specific words and functions
  1318.  
  1319.  
  1320. File Loading
  1321.  
  1322. Currently, files are loaded into a 16K buffer and compiled in one
  1323. pass.  This will be changed in future releases to support line-by-line
  1324. compilation.  So, the file size limit for FORTH.INI is currently 16K.
  1325.  
  1326. Block files are not directly supported.  A preliminary block file handler
  1327. has been implemented using the OS/2 functions SYS$READ, SYS$SEEK, and
  1328. SYS$WRITE in the file BLOCKS.4TH.
  1329.  
  1330.  
  1331.  
  1332. WORD and Strings
  1333.  
  1334. All string lengths are fully 32-bits long (no 255-character limits on
  1335. strings.)  This will certainly cause problems if you are using
  1336. COUNT.  If so, replace it with @+ which does the same thing except for
  1337. using a 32-bit count.  Remember, though, that doing a C@ on the string
  1338. will return the correct length if it is less than 256 characters long
  1339. because the 80386 stores the least significant byte in lower memory.
  1340. And, using it the normal way will usually do no harm.  You will simply
  1341. be typing out extra zeros in the front and chopping off the last three
  1342. characters.
  1343.  
  1344. Feel free to redefine COUNT if necessary, but people often use COUNT
  1345. for purposes other than with strings, so it was left alone.
  1346.  
  1347. Or, redefine WORD like this:
  1348.  
  1349.     : WORD ( char string"-- addr ) WORD  DUP C@  OVER 3 + C!  3 + ;
  1350.  
  1351. which stores an extra copy of the count immediately before the first
  1352. character, and returns that address instead.  Be careful, however, to
  1353. redefine some of the system functions such as ". because these fetch
  1354. the full 32-bit length.
  1355.  
  1356. WORD will not work accross lines while loading a file.
  1357.  
  1358.  
  1359.  
  1360. " (Quotes)
  1361.  
  1362. " string" returns the address of 32-bit count of a counted string.
  1363.  
  1364.  
  1365.  
  1366. Dictionary Headers and ' (tick)
  1367.  
  1368. The dictionary structure reflects the fully 32-bit theme of this
  1369. Forth.  All fields, including the length of the word, are 32 bits long.
  1370. A separate 32-bit flag field replaces the use of bits 6 and 7
  1371. of the length byte of typical Forths.  The word IMMEDIATE works in
  1372. the usual way, however.  It sets bit 1 (of 0-31) of the flag field.
  1373.  
  1374. The name field is always set to 32 bytes.  With 4GB of virtual memory to
  1375. play with, code size was not a major concern.
  1376.  
  1377. The order of the dictionary fields is non-standard.  The dictionary
  1378. header is structured like this:
  1379.  
  1380. Field    Length
  1381. Name    in bytes   Contents
  1382. -----   --------   --------------------------------------------------------
  1383. LFA         4      Link Field Address, link to previous definition
  1384. FFA         4      Flag Field Address, flags immediate definitions
  1385. CFA         4      Code Field Address, pointer to executable code
  1386. NFA         4      Name Field Address, length of the word followed by
  1387. SFA        32      String Field Address, address of first character
  1388. PFA         ?      Parameter Field Address, start of code and/or parameters
  1389.  
  1390. The string field is initialized to zeros.
  1391.  
  1392. ' (tick) returns the address of the link field address of the word, the
  1393. start of the definition.  To get to the other fields, use the following
  1394. words:
  1395.  
  1396.   ' <word>  ==>  LFA of word, then use:
  1397.  
  1398. DECIMAL
  1399.   : FFA  04 + ;  ( converts  LFA  to  FFA  or  Flag Field Address )
  1400.   : CFA  08 + ;  ( converts  LFA  to  CFA  or  Code Field Address )
  1401.   : NFA  12 + ;  ( converts  LFA  to  NFA  or  Name Field Address )
  1402.   : SFA  16 + ;  ( converts  LFA  to  SFA  or  String Field Address )
  1403.   : PFA  32 + ;  ( converts  LFA  to  PFA  or  Parameter Field Address )
  1404.  
  1405.   : LFA  32 - ;  ( converts  PFA  to  LFA )
  1406.  
  1407. If you ' a constant or a word created with DOES> you will have to add 5
  1408. to the address to get the real parameters.  The 5 skips the jump opcode
  1409. and the four byte offset.
  1410.  
  1411.  
  1412.  
  1413. TIB
  1414.  
  1415. The word TIB returns the address of a variable which holds the location
  1416. of the terminal input buffer.  To make it compatible, redefine
  1417.    :  TIB TIB @ ;
  1418. (It seems to be more flexible as a pointer anyway.)
  1419.  
  1420.  
  1421.  
  1422. Dictionary Pointer
  1423.  
  1424. Currently the dictionary pointer cannot be externally accessed with a
  1425. variable address.  Instead, use HERE to get the current dictionary
  1426. pointer and use DP!  to store into the dictionary pointer (instead of
  1427. DP !).
  1428.  
  1429.  
  1430.  
  1431. CASE
  1432.  
  1433. An implementation of Chuck Eaker's CASE words is included in the
  1434. FORTH.INI file.  There is one major difference.  You must do a DROP or
  1435. equivalent before the ENDOF statement at the end.  This was done because
  1436. you should not have to DUP the value which fell through in order to
  1437. handle it (as in 0 DAY in section 3.1).  It does not make sense that
  1438. ENDCASE requires a parameter.  It DOES make sense that you should always
  1439. deal with an exception, either by ignoring it with DROP or by using some
  1440. type of error handling.
  1441.  
  1442.  
  1443.  
  1444.  
  1445. 7.  WHERE TO SEND COMMENTS AND SUGGESTIONS
  1446.  
  1447. Mike Warot (ka9dgx) created Forth/2 and welcomes any comments,
  1448. or suggestions about improving this product.  You may contact him
  1449. via email over the Internet at:
  1450.  
  1451.      ka9dgx@chinet.com             OR  ka9dgx@aol.com
  1452.  
  1453. or via USMail at:
  1454.  
  1455.      Mike Warot
  1456.      PO BOX 4043
  1457.      Hammond, Indiana 46324
  1458.  
  1459. Also contact Mike about licensing this product and obtaining the source
  1460. code for Forth/2.
  1461.  
  1462.  
  1463. Brian Mathewson has helped Mike develop this Forth and the documentation.
  1464. Please send any special requests, ideas, or suggestions to:
  1465.  
  1466.      bbm@r2d2.eeap.cwru.edu
  1467.  
  1468. or via USMail at:
  1469.  
  1470.      Brian Mathewson
  1471.      21576 Kenwood Avenue
  1472.      Rocky River, OH  44116-1232
  1473.  
  1474. <<< End of Forth/2 Documentation  23 March 1993 >>>
  1475.