Borland Programmer's Resource

home *** CD-ROM | disk | FTP | other *** search

/ Borland Programmer's Resource / Borland_Programmers_Resource_CD_1995.iso / ntcode / jx4nt125 / doc / jax4th.doc

Wrap

Text File | 1995-05-19 | 96.6 KB | 2,423 lines

Jax4th for Windows NT is Copyright 1993, 1994 by Jack J. Woehr, PO Box 51, Golden, CO 80402-0051 jax@well.sf.ca.us 72203.1320@compuserve.com SYSOP RCFB (303) 278-0364 All Rights Reserved. NOTE: This document is formatted to a maximum of 120 characters per line. With a 640x480 display, Alan Phillips's PFE editor for NT using the screen font Lucida Sans Typewriter 7 is best for viewing. The Gnu Public License is Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, Inc. ********************************************************************* This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (see COPYING.TXT) You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ********************************************************* ***For a Quick Start, see the "Invoking Jax4th" section below in this document.*** PRELIMINARY DOCUMENTATION -- to be finished Real Soon Now :-) ------------------------------------------------------------- This preliminary documentation file is still undergoing revision, as is the Jax4th system itself. This documentation is not yet complete, but attempts in as far as it is complete to conform to the documentation requirements imposed by the ANS/ASC X3/X3J14 Standard for Forth (ANSI/IEEE X3.215-1994) in Chapter Four "Documentation Requirements" of that draft. A GLOSSARY IS AT THE END OF THIS DOCUMENT. - To be kept up-to-date on Jax4th, see the heading "OPTIONAL SHAREWARE REGISTRATION" below. - For information on Jax4th's TOTAL LACK OF WARRANTY, see the Gnu Public License in the file LICENSE.TXT in the distribution archive in which your received this file. If you did not receive the license, you do not have a licensed copy of Jax4th. - For information on your license to use and right to distribute this free system, see Gnu Public License, vide infra (how's *that* for lawyer talk?!). - For information on X3J14 and the draft proposed Standard, contact the X3J14 Technical Committee, c/o Elizabeth Rather, Chair, 111 N. Sepulveda Blvd., Suite 300, Manhattan Beach, CA 90266. Welcome to Jax4th for Windows NT Version 1.x! --------------------------------------------- Jax4th is a minimal model Forth system. The design goals are as follows: 1) Provide a fun freeware Forth for Windows NT which is as complete, usefula and easy to use as is practical in the limited amount of time the author has to develop and maintain it. 2) Provide a Forth as described above which emphasizes the model promulgated by the ANS/ASC X3/X3J14 Technical Committe for ANS Forth. LATE NOTE: As Elizabeth Rather, Chair of X3J14 posted on USENET April 19, 1994: "I'm happy to inform you that, according to Lynn Barra of X3, the ANSI BSR letter ballot for final approval of ANS Forth passed. Lynn believes they will take about 2 mos. to publish the document, and will issue a press release when it is ready." For a Quick Start, see the "Invoking Jax4th" section below in this document. What Jax4th is Not ------------------ Jax4th is not an optimizing compiler targeted at professional development. The author did not dream of providing in two hundred (200) hours of his time a freeware Forth to compete with professional systems which required thousands of hours of programmer time to complete. For a professional Forth development environment for Windows 3.1 or for Windows NT, please contact a Forth vendor, for instance, one of the organizations listed below (in alphabetical order): FORTH, Inc. 111 N. Sepulveda Blvd. Manhattan Beach, CA 90266 1-800-55-FORTH Laboratory Microsystems, Inc. (LMI) P.O. Box 10430 Marina del Rey, CA 90295 1-310-306-7412 Microprocessor Engineering, Ltc. (MPE) 133 Hill Lane Surrey, Southampton SO1 5AF England +011-44-703-631441 About Forth ----------- The author of Jax4th has written two books on Forth: _Forth: The New Model_, Jack Woehr M&T Publishing, 1992, ISBN 1-55851-277-2 (about dpANS-Forth); _Seeing Forth_, Jack Woehr, Offete Enterprises, 1992 (about Forth history and philosophy). Both of these books, as well as many others fine Forth books by many fine authors, may be mail-ordered from: The Forth Interest Group P.O. Box 2154 Oakland, CA 94621 1-510-89-FORTH DISCLAIMERS ----------- 1) JaxFamousFreewareDisclaimer: ****************************************************************** * NO WARRANTY NO GUARANTEE NO SOAP RADIO, YER' ON YER OWN, SIS/BUB! * ****************************************************************** 2) All trademarks mentioned herein are the property of their owners. The owners are so obvious as not to bear mentioning, other than to tell you once that "Windows NT is a trademark of Microsoft". Duh. 3) The draft proposed Standard for Forth is the work of the ANS/ASC X3/X3J14 Technical Committee, a committee accredited to CBEMA and the American National Standards Institute. Please note that when the phrase "ANS Forth" appears, it refers to the model of Forth which will result from the X3J14 Technical Committee's deliberations, once promulgated by the American National Standards Institute. The draft was recently reported as having been passed by X3, see note above. LICENSE & DISTRIBUTION ---------------------- Jax4th is licensed under the GNU public license. For information on the GNU public license, read the file LICENSE.TXT or please contact the Free Software Foundation, Inc., 675 Mass. Ave., Cambridge, MA 02139. This free software is not warrantied or guaranteed in any fashion. I just happen to like it ... OPTIONAL SHAREWARE REGISTRATION ------------------------------- Jax4th is GNU-style Freeware, but if you send a $25.00 donation to the author: Jack Woehr PO Box 51 Golden, CO 80402-0051 accompanied by an internet email address, you will be kept posted on major upgrades (including later additions to this documentation!!) via UUENCODEd .ZIP files. Your registration will last for one (1) year from the date it is received. PLEASE SEND U.S. CHECK OR MONEY ORDER ONLY ... NO CASH NO CREDIT CARDS NO FOREIGN CHECKS. Your donation is entirely voluntary, since from time to time I will post these same files to public download sites. Your donation simply expresses respect for the author and adds to your convenience in keeping up with upgrades to this model Forth system. Since your donation is voluntary, no extension of Jax4th's complete NON-WARRANTY is effected by such donation: JAX4TH IS NEVER SOLD. All tech support is currently provided via the RCFB BBS (303) 278-0364. (J)oin JAXWARE when you are there. No tech support is promised for this free software, but it's my BBS, so I'll be there maybe. Invoking Jax4th ---------------- Doubleclick on JAX4TH.EXE in File Manager, or doubleclick the Jax4th icon in a program group or icon bar to start Jax4th for Windows NT. Alternatively type JAX4TH to start the system. Any other valid Forth commands entered on the command line will be executed before the Jax4th logo is displayed and QUIT is performed. If you have a saved dictionary, e.g., FOO.DIC, you may reload it on the command line and execute commands from it C:\>jax4th RELOAD FOO.DIC MY-WORD BYE for example. Use CAPS LOCK ON since Jax4th's interpreter is case sensitive and most system words are in UPPERCASE. JAX4TH gives you a compiler/interpreter with no mass storage facilities. User dictionary is 32K, data space is 32K. Both will overflow silently if exhausted. Saving a Dictionary ------------------- You may compile code and then save the resultant dictionary image for later reloading. To save, type SAVE-FORTH, which brings up a requester for a "save file as" name. BUG: The requester doesn't always come to front, you may have to go look for it behind your window! Choose a filename and click "OK" and your dictionary will be saved for a later reload without recompilation. LIMITATION: Don't SAVE-FORTH with any wordlists in the search order or current compilation wordlist EXCEPT those from among the predefined system wordlists: FORTH-WORDLIST INTERNALS-WORDLIST SYSTEM-WORDLIST and NONSTANDARD-WORDLIST. Instead, your program should set the search order ynamically at runtime. See: SAVE-FORTH RELOAD RELOAD-FILE RELOADED Recompilation of Jax4th ----------------------- To compile Jax4th from the sources provided you will need: - Microsoft MASM 6.11 or later (thanx for the beta, Microsoft!) For compiling Jax4th for Windows NT: - The Windows NT SDK and a 32 bit linker, such as LINK32 from the beta NT SDK. A Makefile for NMAKE is provided. Standard System --------------- Jax4th is a model system conforming to the current state of the draft proposed Standard Forth (ANSI/IEEE X3.215-199x) to the best of the author's understanding. The following dpANS word sets are provided in their entirety: Core Block Exception-Handling Memory-Allocation (*note: Memory-Allocation wordset provided in loadable source form.) Search-Order The following wordsets are substantially provided in Jax4th with some non-conformance noted later in this document: File-Access String Selected words from the following wordsets are present in Jax4th: Core Extensions Double-Number (and Extensions) Facility Programming-Tools The following word sets are not supported at all in the current revision of Jax4th. Some may be supported or partially supported in future revisions: Floating-Point Locals See the Glossary later in this document for more information. General Implementation Options ---------------------- Aligned address requirements: ALIGN aligns the dataspace to longword (4 bytes) boundaries. In general, the system is thus aligned, though as regards the dictionary (as opposed to data space) this should be transparent to the user. See, however, "Character-aligned address requirements" below. Behavior of EMIT for non-displayable values: The Unicode support for the Windows NT Console tends to display question marks ("?") for non-printable values. Character-aligned address requirements: Jax4th characters are Unicode, and must be word (2 byte) aligned. See also: ASCIIZ and UNICODE in the "Glossary" later in this document. Also, see "File Handling, ASCII and Unicode" later in this document. Character editing of ACCEPT: The line-editing performed by Jax4th ACCEPT is provided by the Windows NT Console. DOSKEY-based command-line edits and recall via the arrow keys is supported. Control-flow stack: The data stack is the control-flow stack. No type checking on control structure information is performed. User output device: The user output device is the Windows NT Console. Display after return of ACCEPT: The NT Console emits a CR/LF pair when the user terminates ACCEPT. Exception abort sequence: ABORT and ABORT" are implemented in terms of CATCH/THROW. At powerup, an initial CATCH frame is pushed on the exception stack which catches stray THROWs that are not caught by application code. When such THROWs are caught, the exception stack is re-initialized as before. The exception stack is implemented on the return stack. Certain THROWs are recognized and the default handler for the system CATCH frame prints a message associated with them. If a THROW hits the system CATCH frame and the THROW number is not recognized, a message indicating the THROW number and the address at which it occurred is printed. In the case of ABORT, no message is printed, but the following actions occur: - The initial CATCH frame is restored. - The return stack is cleared. - The data stack is cleared. - The input stream is restored to the default console input and emptied. - The STATE of the system is restored to "interpreting". Additionally, in the case of ABORT" the user-supplied message string is displayed. Input return key: The input return key is the Enter key. Maximum size of counted string: 65,535 characters. Maximum size of a word name: 126 characters. Maximum string length for ENVIRONMENT?: 65,535 characters. Method of selection of user input device: There is a deficiency in Windows NT Console support for Unicode. WriteFile() doesn't support Unicode to console handles. WriteConsole() doesn't support redirection of console I/O. The result is either Unicode or no command line redirection of I/O for Jax4th. The author chose Unicode; therefore, there is no redirection of console I/O for Jax4th. Method of use of return stack during compilation: The return stack is not used in any special manner during compilation. Methods of dictionary compilation: The data stack is the control flow stack. A name is not linked into the compilation wordlist until the name's definition is complete. A colon definition will not be completed if the data stack depth has changed since the definition was commenced. There is no type checking performed on control flow construct information. There is no warning for name redefinition. Compilation occurs in the user dictionary, which is in a separate address space from the kernel dictionary. Any execution token returned by ' ("tick") may be converted to a data-relative address via the word TOKENTODATA. Methods of memory space management: Data space is separate from dictionary space and commences at a relative address of zero. A data space address must be converted to an absolute address via DATATOABS (q.v., Glossary) before passing such to a Windows NT system call. Any Windows NT memory allocation operation will return an absolute addres which must be converted to a data-relative address before operating upon it with ! or @ etc. via ABSTODATA. See also: ABSTOCODE CODETOABS CODETODATA DATATOCODE TOKENTODATA in the Glossary. Minimum search order: There are four (4) wordlists in the Jax4th kernel: FORTH-WORDLIST all the standard Forth words in the Jax4th system. NONSTANDARD-WORDLIST some familiar, some new, but all nonstandard Forth words. SYSTEM-WORDLIST special words the user needs to interface Jax4th to the host OS. INTERNALS-WORDLIST low-level words used internally, most not of direct use to the programmer. (toti q.v., Glossary). The minimum search order is FORTH-WORDLIST, but the bootup default is FORTH-WORDLIST NONSTANDARD-WORDLIST SYSTEM-WORDLIST in that order. INTERNALS-WORDLIST is interesting, but not generally useful to the programmer, so it is not placed in the search order by default. Number of bits in one address unit: A Jax4th address unit is a byte, eight (8) bits. Number representation: Two's complement. Ranges for: Type Low High ---- --- ---- n -2^31 (2^31)-1 +n 0 (2^31)-1 u 0 (2^32)-1 d -2^63 (2^63)-1 +d 0 (2^63)-1 ud 0 (2^64)-1 Read-only data space regions: The kernel, the user dictionary, and runtime data space loaded by Jax4th may be read. Aside from this space, only readable allocations made by the user via the Jax4th facility to perform Windows NT system calls may be read. All other memory is not readable, albeit addressable. Size of one cell in address units: 4 address units. Size of one character in address units: 2 address units. Size of keyboard terminal input buffer: 256 characters. Size of the pictured numeric output string buffer: 128 characters. Size of PAD: 128 characters. System prompt: The characters ok followed by the depth of the data stack represented in the current numeric base form the system prompt. Type of division: The default division algorithm is "symmetrical about zero". Values returned after arithmetic overflow: Undefined. The current definition may not be found immediately after DOES> until the semicolon (";") which matches the colon (":") which commenced the current definition is encountered by the text interpreter. Wordset-specific Implementation Options --------------------------------------- BLOCK: Format of LIST: Traditional 16 x 64 screen display with header and line numbers on each side. Also, file id is displayed at top of screen. Length of line affected by \: To end of 64-character line. DOUBLE: None. EXCEPTION: List of Throw Codes: Many Jax4th words will THROW a throw code on encountering an error. That THROW will be trapped by a system CATCH unless caught by a user CATCH. The system CATCH either prints a specific message, or returns the number of the THROW. Jax4th does not necessarily trap all error conditions specified below. -1 ABORT -2 ABORT" -3 stack over -4 stack under -5 ret stack over -6 ret stack under -7 too many DO .. LOOPs -8 dictionary space exhausted -9 invalid memory address -10 divide by zero -11 result overflow/underflow -12 wrong arg type -13 word not found -14 compile-only -15 bogus FORGET -16 empty string used for name -17 numeric output string too long -18 parsed string too long -19 name too long -20 illegal memory write -21 unsupported operation -22 control struct mismatch -23 misaligned address -24 invalid numeric argument -25 return stack imbalance -26 loop parameters inaccessible -27 bogus recursion -28 user interrupt -29 attempt to nest definitions -30 obsolescent feature -31 >BODY used on non-CREATEd word -32 invalid name argument -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 BASE for floating point conversion -41 loss of precision -42 floating-point div by zero -43 floating-point result out of range -44 floating-point stack over -45 floating-point stack under -46 floating-point invalid argument -47 compilation word list deleted -48 invalid POSTPONE -49 search-order overflow -50 search-order underflow -51 compilation word list changed during compilation -52 control-flow stack over -53 exception stack over -54 floating-point numeric underflow -55 floating-point unidentified fault -56 QUIT -57 character send/receive exception -58 [IF] [ELSE] or [THEN] exception FACILITY: Encoding of keyboard events re: EKEY: EKEY not currently implemented. Duration of system clock tick: MS not currently implemented. Repeatability to be expected from MS: MS not currently implemented. FILE: <this documentation not finished> File line terminator: <CR><LF> or just <LF>. Maximum size of an input line: 256 characters. Size of string buffer used by S": 256 characters. General Ambiguous Conditions ---------------------------- If the data stack underflows and the interpreter is entered, the condition will be detected and the appropriate THROW (-4, data stack underflow) will be made. Data stack overflow, return stack underflow and return stack overflow at present go undetected in Jax4th. Insufficient space for loop-control parameters at present goes undetected in Jax4th. Insufficient space in the dictionary at present goes undetected in Jax4th. If a program addresses a region which is not readable data space, the Windows NT Executive Virtual Memory Manager will cause an exception which at present will be handled by the Win32 subsystem. Future Jax4th revisions may handle this exception. If a program causes a machine division by zero, the Windows NT Kernel will cause an exception which at present will be handled by the Win32 subsystem. Future Jax4th revisions may handle this exception. A mathematical result out-of-range will be returned silently. Any mathematical shift with an invalid shift-count argument returns an undefined result. An incompatible argument type is rarely recognized by Jax4th, with the exception of passing an execution token not created by CREATE to >BODY, which will cause the appropriate THROW (-31, >BODY used on non-CREATE word). An invalid lexical item (neither a name nor a number in the current base) will cause the interpreter/compiler to perform the appropriate THROW (-13, undefined word). Interpretation of a word with undefined interpretation semantics results in an appropriate THROW (-14, interpretive execution of a compile-only construct). If a POSTPONEd construct is executed at interpret time, the same THROW -14 occurs. Attempting to find an execution token for a defintion with undefined interpretation semantics succeeds. An attempt to use a zero-length string as a name due to input stream exhaustion results in the appropriate THROW (-16, attempt to use zero-length string as a name). Overflow of pictured numeric output string, though unlikely, occurs silently and may compromise Jax4th execution. Parsed string overflow, though unlikely, occurs silently and may compromise Jax4th execution. A word name exceeding the maximum length of a word name results in an undefined condition. No harm to Jax4th execution will occur, but the name may not be findable in a recognizable form, or if findable, may have unexpected attributes, such as unasked-for immediacy. Program modification of the contents of the input stream or of a string literal are harmless, except, possibly, to the meaning of the program. Other ambiguous conditions are documented in the Glossary under the heading for the word to which they pertain. Wordset-specific Ambiguous Conditions ------------------------------------- BLOCK: Correct BLOCK read impossible: Appropriate THROW is made depending on cause of error. I/O exception in BLOCK transfer: Appropriate THROW is made depending on cause of error. Invalid BLOCK number: Appropriate THROW is made depending on cause of error. A program directly alters contents of BLK: Undefined; better not do it! No current block buffer for UPDATE: Undefined. DOUBLE: d outside range of n in D>S: Silent truncation. EXCEPTION: None. FACILITY: AT-XY operation can't be performed on user output device: Undefined. FILE: Attempt to position a file outside its boundaries: Should be an appropriate ior or THROW, but NT appears to accept such an operation. Attempting to read from file position not yet written: Undefined. fileid is invalid: Appropriate ior or THROW. I/O exception reading or closing fileid: Appropriate ior or THROW. Named file cannot be opened: Appropriate ior or THROW. Requesting an unmapped BLOCK number. Appropriate ior or THROW. Using SOURCE-ID when BLK is not zero: Undefined. Other General System Documentation ---------------------------------- System dictionary space: Currently, 65,536 address units. Available application data space: Currently, 65,536 address units minus the value returned by HERE at powerup. Data stack space: Currently, 4096 cells. Return stack space: Currently, 4096 cells. Operator's terminal facilities: By default, the Windows NT Console, but there's a whole world of GUI waiting out there! Other Wordset-Specific System Documentation ------------------------------------------- BLOCK: Restrictions which multiprogramming places on use of buffer addresses: Jax4th does not support multiprogramming. Number of BLOCKs available for source text and data: Limited by file size. DOUBLE: None. EXCEPTION: None. FACILITY: None. FILE: None. Non-Conformance --------------- In the areas discussed below, Jax4th is either non-conforming to the intent of the draft proposed Standard Forth or of questionable conformity. Facility: We ought to make KEY? conform a little more closely to what KEY returns below 1Bh. Also, KEY? should be discarding non-char-set events it encounters up until the first, then should discard no more until KEY is called. We are non-conforming here in that we don't discard, but KEY *does* discard the non-char-set key events. However, after calling KEY? successfully, EKEY could conceivabley find a non-char-set key event preceding the char which triggered the KEY? flag, which doesn't seem to be what the Standard intends 10.6.1.1755. File Word Set: ( "paren" is non-compliant in that it does not span multiple lines of source seeking its matching right-paren. String Word Set: Of the entire String word set, only SEARCH is not present in the current revision of Jax4th. File-Handling, ASCII and Unicode -------------------------------- Realize that READ-FILE WRITE-FILE FILE-POSITION REPOSITION-FILE, etc. are supposed in ANS Forth to deal with "characters". To deal with this, we created parallel defs, e.g., READ-FILEA (ascii) READ-FILEW (wide-char unicode) and a DEFERred READ-FILE which is vectored by default at powerup (in COLD) to READ-FILEW. If you want to change the vector for READ-FILEA to read ASCII files, then ' READ-FILEA ' READ-FILE >BDDY ! is sufficient. Affected words, all of which are now deferred words, vectored by default at powerup to their Unicode versions (e.g., FILE-POSITION executes FILE-POSITIONW instead of FILE-POSITIONA): FILE-POSITION FILE-SIZE READ-FILE REPOSITION-FILE RESIZE-FILE WRITE-FILE The word READ-LINE is currently Unicode only. NOTE!!! that BLOCK always reads characters, not bytes. The ANSI definition of a BLOCK is 1024 characters, so BLOCK calls READ-FILEW WRITE-FILEW etc. directly. BLOCK is *not* affected by any revectoring you do. See below: "BLOCK File Loading in Jax4th" and "Unicode Text File Loading in Jax4th". NOTE!!! The S" in Jax4th appends a null character 0x0000 to the end of the string which it parses. If you need a null-terminated string for a system call, just DROP the count from such a string. Selected Low-Level Details about Jax4th --------------------------------------- The method of compilation of kernel addresses may not work forever. Currently in NT, on loading code it loads at the same address each time, but that may not last. In any event, the user will have to recompile saved dictionaries each new release of Jax4th and probably each new release of NT. Alternatively, we could do runtime relocation of dictionary. Of course, if we went that far, why not go for a subroutine-threaded design? The Console handles are exposed in Jax4th so you can go wild and play with the Console capabilities of NT from within Jax4th if you are up to programming it. The VARIABLEs StdIn StdOut and StdErr contain the handles you need. Also see ConsoleMode GetConsoleMode and SetConsoleMode (in the source code if I haven't managed to get info into the Glossary by the time you read this. Structs are weird between MASM and Windows NT. For instance, the INPUT_RECORD structure defines the InputRecord.EventType as WORD but you have to say DWORD in MASM in this instance (WINDOWS.I) and then in referencing the data use WORD to avoid getting garbage (see the source KEY? in JAX4TH.A). The alignment factor as treated by MASM isn't always automatically the same as the alignment factor in the C includes. Stylistic --------- As simple and good-old as this Forth can be made. Indirect threaded. Going beyond the CORE, it's not exactly the minimal implementation, but pretty much just that I felt made a compact yet complete system. Forth programmers don't need floating point or local variables, but they *do* like DUMP. Loading Source Code in Jax4th ----------------------------- The draft proposed Standard for Forth mandates that if any file-loading capabilities are present in a Standard System, the classic Forth mass storage mechanism BLOCK must be present. Loading prepared program source into Jax4th is done via this BLOCK mechanism or via loading from a text file. Both BLOCK files and text files for Jax4th must be Unicode, not ASCII. See below about converting and loading BLOCK and text files. Converting ASCII BLOCK and Text Files to Unicode BLOCK and Text Files --------------------------------------------------------------------- While classic Forth BLOCKs consist of 1024 bytes, ANS Forth says that a BLOCK consists of 1024 characters. A character in Jax4th is 16 bits wide (Unicode), so a BLOCK file edited under a typical Forth BLOCK editor won't load in Jax4th without massaging. Since Jax4th doesn't have a very good BLOCK editor yet, this could be a drawback. However, we have provided file massaging utilities coded in C to allow you to use a BLOCK editor from another Forth system to do development. UNIBLOCK.EXE [sourcefile destfile ]|[/?] converts an ASCII file sourcefile to a Unicode file destfile. Type UNIBLOCK /? for help. UNIASCII.EXE [sourcefile destfile ]|[/?] converts a Unicode file sourcefile to an ASCII file destfile. Type UNIASCII /? for help. Both these utilities work on text files as well as BLOCK files. Note: The BLOCK (*.BLK) and text files (*.UTF) distributed with Jax4th are already converted! The only non-Unicode source file included is EXAMPLES\SHORTEST.F which is used to demonstrate DDE pasting of ASCII source into Unicode Jax4th. Don't convert SHORTEST.F! BLOCK File Loading in Jax4th ---------------------------- To open a BLOCK file, use OPEN-FILE: S" EXAMPLE\JX4EXAMP.BLK" R/W OPEN-FILE If the return from OPEN-FILE is zero (0), the operation was successful and the file handle is on the data stack. Store that file handle in the system variable BLOCK-FILE: BLOCK-FILE ! After that you may use LIST and LOAD and they will perform as they always have in Forth. Unicode Text File Loading in Jax4th ------------------------------------ Jax4th interprets text files. However, they have to be UNICODE text files. UNIPAD in the Windows NT %MSTOOLS%\BIN directory is brain-dead and buggy. One way to deal with Unicode is to use UNIBLOCK.EXE to convert the text files you are editing to Unicode files. (It's *called* UNIBLOCK but it doesn't really care if it's a BLOCK file or a plain text file. I am using the .UTF extension for Unicode text files since that's what Unipad wants to do. To interpret a text file, pass a valid file id to INCLUDE-FILE. S" UTILS\UB2T.UTF" R/O OPEN-FILE . 0 ok1 VARIABLE MyFile ! ok0 MyFile @ INCLUDE-FILE ok \ Text will have been interpreted before this prompt appears. Alternatively, used INCLUDED, e.g., S" UTILS\UB2T.UTF" INCLUDED ok \ Text will have been interpreted before this prompt appears. Of course, you could just define INCLUDE as follows: : INCLUDE BL WORD COUNT INCLUDED ; ok INCLUDE UTILS\UB2T.UT ok \ Text will have been interpreted before this prompt appears. which is probably the best way to go. NOTE: Jax4th doesn't handle embedded tabs or other control chars (except CR & LF) yet. Make sure your text editor is doing "soft tabs". i.e., inserting four or more spaces for tabs instead of hex 09 characters. NOTE: Paren "(" is non-compliant with the Standard in that it doesn't span multiple lines of text file interpretation while awaiting its matching right-paren ")". (I voted against that stupid idea on X3J14, by the way). Will fix this Real Soon Now. Making Windows NT System Calls from Jax4th ------------------------------------------- There are several words of interest to one desiring to write Windows NT system calls in Jax4th. Their explanations should be examined in the Glossary of this document: ASCIIZ DATATOABS GetProcAddress FreeLibrary LoadLibraryEx SYSCALL The procedure is as follows: 1) Load the library using LoadLibraryEx and save the handle in a variable. Make sure you got a valid handle back, and not a NULL. 2) Use GetProcAddress to get the addresses of any calls you wish to make. 3) Push parameters on stack right-to-left from their formal parameters as documented in the Windows NT SDK, taking care to convert Forth data-relative addresses to absolute addresses via DATATOABS. 4) Push address obtained from GetProcAddress on stack and execute SYSCALL. The returns in EDX and EAX will be found on the stack afterwards. 5) Use FreeLibrary to free the library reference made by the earlier LoadLibraryEx. Note the funny aspect of NT that LoadLibraryEx takes Unicode strings for library names, but GetProcAddress only accepts ASCIIZ strings. Therefore, we have provided ASCIIZ to return the address of a null-terminated byte string for this sort of system call. Here is an example of using the system call Beep(dwFreq,dwDuration) VARIABLE KERNEL32 0 0 S" KERNEL32.DLL" DROP DATATOABS LoadLibraryEx KERNEL32 ! VARIABLE SYSBEEP S" Beep" ASCIIZ DATATOABS KERNEL32 @ GetProcAddress SYSBEEP ! 1000 ( duration) 440 ( frequency) SYSBEEP @ SYSCALL ( Beeps A:440 for 1 second.) The above example will leave two (2) items on the stack: the contents of the registers EDX and EAX. Windows NT DLLs return singles in EAX and doubles in EDX:EAX. I probably should change the order in which these are returned on the stack ... currently EAX, which is more often useful, is on top. Note that you do not have to re-open the library and re-resolve the procedure address every time you make the call, but you must do so each time you load your Forth image, since these addresses and handles are not fixed. Before you exit, you should close the libraries you opened. KERNEL32 @ FreeLibrary ... will do the trick in the above example. NOTE: An example of writing a nice front end to Windows NT System Calls is found in UTILS\SYSCALLS.UTF. Example Source Code ------------------- There are three directories of Forth source code, \EXAMPLE \UTILS and \OBJ4TH. \EXAMPLE contains a Unicode BLOCK file called PASTE.BLK prepared by Clifford L. King of Micro K Systems, Aurora, Colorado, along with an ASCII test file SHORTEST.F. PASTE.BLK demonstrates DDE in Jax4th. \UTILS contains Unicode text files: UTILS\UTILS.UTF Unicode text source for various utilities. UTILS\EDITOR.UTF Unicode text source for a simple Unicode BLOCK file editor. UTILS\MEMORY.UTF Unicode text source for the Memory Allocation word set. UTILS\SYSCALLS.UTF Unicode text source examples of Jax4th system calls to NT DLLs. UTILS\UB2T.UTF Unicode text source for program to convert Unicode BLOCK files to Unicode text files. UTILS\YIQING.UTF Cast the Yi Qing oracle. \OBJ4TH contains files imlementing some object extensions stuff. OBJ4TH\DIMARRAY.UTF DIMARRAY, a CREATEing word which creates n-dimensioned self-indexing arrays. OBJ4TH\MULTIOOP.UTF Multiple-inheritance data objects. The syntax in accessing such objects, once defined with methods, is n1 .. nm method object OBJ4TH\OOPSOBJS.UTF Sample object defined under MULTIOOP. For example, to create an array of characters after loading this file you might type: 10 CHAR-ARRAY FOO then store to the first, second and third elemes of it: CHAR Z 0 `TO' FOO CHAR E 1 `TO' FOO CHAR D 3 `TO' FOO and then checksum them all with: `CHECKSUM' FOO NOTE!!! that the files are somewhat mutually dependent, but have a rudimentary conditional include facility (awaiting my implementation of [IF] [ELSE] and [THEN]). They expect that Jax4th has been launched in the top-level Jax4th directory with the other descendant directorys present, so if you didn't unzip preserving directory structures, e.g., PKUNZIP -D , then you had better do that now. To Do ----- KEY KEY? EKEY EKEY? are working but I think I have to make KEY? conform a little more closely to what KEY returns. Also, KEY? should be discarding non-char-set events it encounters up until the first, then should discard no more until KEY is called. We are non-conforming here. Finish cleaning up struct declarations in WINDOWS.I. Change WORDLISTS so they return tokens instead of addresses so that user can save images which have non-system wordlists in the search order at SAVE-FORTH time. Glossary of Jax4th ------------------ !!!***!!! This Glossary is not finished, but it does contain all the words in Jax4th. Here is a sorted list of all words in Jax4th, with their stack arguments, the wordlist in which they are found, and a brief definition. The dpANS-Forth word set (if any) from which the word is taken is indicated. The definitions contained herein are NOT OFFICIAL DEFINITIONS. For more information, see the Standard itself [ANSI/IEEE X3.215-199x]. THIS GLOSSARY IS NOT A FORTH TUTORIAL! The entry for >R notes that the top data stack item moves to the return stack, but doesn't tell you what every Forther knows, that that same item had better be moved off before the next semi-colon is hit. Key to stack abbreviations: --------------------------- x any single-cell stack item xd any double-cell stack item n any signed single-cell integer +,-n any positive,negative single-cell integer d any signed double-cell integer +,-d any positive,negative double-cell integer u any unsigned single-cell integer ud any unsigned double-cell integer c a character "ccc" a string of characters in the input stream "ccc<a>" a string of characters in the input stream terminated by a character <a> name a Forth word's name in the input stream addr an address in Forth data space a-addr a cell-aligned address in Forth data space c-addr a character-aligned address in Forth data space xt an execution token R: happening on the return stack C: happening on the control flow stack Notes: - An "aligned address" is one that falls on a boundary fitting the host architecture. In the case of Jax4th for Windows NT, that's on a word (16-bit) boundary, an even address. - The gloss "iff" is to be read as in logic, "if-and-only-if". The Words --------- ! ; x a-addr -- FORTH-WORDLIST CORE Store cell x at a-addr. # ; ud1 -- ud2 FORTH-WORDLIST CORE ud2 is ud1's double integer quotient by BASE @. The modulus of character width is deposited at the current index into the pictured numeric output string buffer. #> ; ud -- c-addr u FORTH-WORDLIST CORE ud is discarded and the address and count of the pictured numeric output string stored in the transient pictured numeric output string buffer is returned. #S ; ud1 -- ud2 FORTH-WORDLIST CORE perform successive # operations on ud1 until ud2 is zero (0). #TIB ; -- c-addr FORTH-WORDLIST CORE EXT variable holding number of chars ACCEPTed into TIB the last time TIB got filled. ' ; -- xt | abort FORTH-WORDLIST CORE consume a word from the input stream and find it in one of the wordlists in the search order. Return the word's execution token, or THROW a -13 if the word is not found. 'TIB ; -- a-addr NONSTANDARD-WORDLIST --- address of the TIB. Standard programs don't modify the data at that address. (ACCEPT) ; c-addr +n1 -- +n2 INTERNALS-WORDLIST --- interal to ACCEPT. (PARSE) ; char "ccc<char>" -- c-addr u INTERNALS-WORDLIST --- interal to PARSE. ( ; "ccc<)>" -- FORTH-WORDLIST CORE Parse up to the next ) and discard. If no ) is found to the end of the input stream, discard entire remainder of input stream. * ; n|u1 n|u2 -- n|u3 FORTH-WORDLIST CORE Multiply n|u1 by n|u2 returning n|u3. */ ; n1 n2 n3 -- n4 FORTH-WORDLIST CORE Multiply n1 by n2 and divide the intermediate double product by n3 yielding quotient n4. Follows default signed division algorithm. */MOD ; n1 n2 n3 -- n4 n5 FORTH-WORDLIST CORE As */ but returning remainder n4 and quotient n5. Follows default signed division algorithm. + ; n|u1 n|u2 -- n|u3 FORTH-WORDLIST CORE Addition. +! ; x a-addr -- FORTH-WORDLIST CORE Increment the datum stored a x-addr by the value of x. In the case of overflow/underflow of the incremented value, Jax4th silently two's-complement wraps. +LOOP ; u -- FORTH-WORDLIST CORE Loop back to the syntactically enclosing DO, having added x to the loop index. , ; x -- FORTH-WORDLIST CORE Store the cell value x to the next available cell in data space and advance the allotment pointer whose value is returned by HERE by value of one cell. - ; n|u1 n|u2 -- n|u3 FORTH-WORDLIST CORE Subtraction. -ROT ; x1 x2 x3 -- x3 x1 x2 NONSTANDARD-WORDLIST --- Rotate the top data element to third-on-stack. -TRAILING ; c-addr1 u1 -- c-addr1 u2 FORTH-WORDLIST CORE Shorten the string count u1 by subtracting the count of trailing blanks to yield u2. . ; n -- FORTH-WORDLIST CORE Print to the current output device the signed single n in the current number base. ." ; Interp -- c-addr u Compile -- FORTH-WORDLIST CORE When encountered, compile the following characters in the input stream until the end of the input stream or until a " is encountered into the dictionary with the runtime routine to print the string thus compiled to the current output device. .. ; i*x -- NONSTANDARD-WORDLIST --- Print the entire data stack destructively. .NAME ; c-addr -- NONSTANDARD-WORDLIST --- Print out a name header. ' DUP TOKENTODATA EXETONAME .NAME will print DUP. .S ; i*x -- i*x FORTH-WORDLIST TOOLS Print the entire data stack non-destructively. .WID ; wid -- NONSTANDARD-WORDLIST --- Print the name and wid of the wordlist represented by WID. .WORD ; link-token -- INTERNALS-WORDLIST --- Print out the name of a word whose link token is on the stack. / ; n1 n2 -- n3 FORTH-WORDLIST CORE Divide signed single n1 by signed single n2 returning the quotient n3, according to default signed division algorithm. /MOD ; n1 n2 -- n3 n4 FORTH-WORDLIST CORE As / but returning remainder n3 and quotient n4. /STRING ; c-addr1 u1 n -- c-addr2 u2 FORTH-WORDLIST CORE Index into a string by n characters. 0< ; x -- flag FORTH-WORDLIST STRING TRUE iff x viewed as a signed single is less than zero. 0<> ; x -- flag FORTH-WORDLIST CORE TRUE iff x is non-zero. 0= ; x -- flag FORTH-WORDLIST CORE EXT TRUE iff x is zero. 0> ; x -- flag FORTH-WORDLIST CORE TRUE iff x viewed as a signed single is greater than zero. 1+ ; n|u1 -- n|u2 FORTH-WORDLIST CORE Add one (1) to two's-complement wrapping n|u1. 1- ; n|u1 -- n|u2 FORTH-WORDLIST CORE Subtract one (1) from two's-complement wrapping n|u1. 2! ; x1 x2 a-addr -- FORTH-WORDLIST CORE Store a double-cell number at the two cells starting at a-addr. Store in the order x2 x1. 2* ; x1 -- x2 FORTH-WORDLIST CORE Left-shift x1 one bit, shifting zeroes into the lowest bit. 2/ ; x1 -- x2 FORTH-WORDLIST CORE Right-shift x1 one bit, shifting zeroes into the highest bit. 2>R ; x1 x2 -- R: -- x1 x2 FORTH-WORDLIST CORE EXT Move two items from data stack to return stack in specific order. See 2R> 2@ ; a-addr -- x1 x2 FORTH-WORDLIST DOUBLE Fetch the double-cell item stored at a-addr to the data stack. 2DROP ; x1 x2 -- FORTH-WORDLIST CORE Drop top two stack items. 2DUP ; x1 x2 -- x1 x2 x1 x2 FORTH-WORDLIST CORE Duplicate top double-cell stack entry. 2LITERAL ; x x -- FORTH-WORDLIST CORE Consume at compile time the top two stack entries and compile as a double-cell literal to be deposited on the runtime stack at execution of the construct into which the 2LITERAL is compiled. 2OVER ; x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 FORTH-WORDLIST CORE Copy the second double-cell data stack entry over the top double-cell data stack entry. 2R> ; -- x1 x2 R: x1 x2 -- FORTH-WORDLIST CORE EXT Undo the effect of 2>R (q.v.) returning two items from the return stack to the data stack in specific order. 2SWAP ; x1 x2 x3 x4 -- x3 x4 x1 x2 FORTH-WORDLIST CORE Swap the top two double-cell data stack entries. : ; -- FORTH-WORDLIST CORE Parse a name from the input stream and start a new definition. Saves an internal record of the depth of the data stack at start of compilation. :NONAME ; --xt FORTH-WORDLIST CORE Start a headerless definition whose execution token will be deposited on the data stack after the next occurence of ; (semi-colon). Saves an internal record of the depth of the data stack at start of compilation. ; ; -- FORTH-WORDLIST CORE EXT Terminate a definition commenced by ; (colon) or :NONAME. See if depth of stack has changed since initiation of compilation. THROW a -52 if depth has changed. < ; n1 n2 -- flag FORTH-WORDLIST CORE TRUE iff signed single n1 is less than signed single n2. <# ; -- FORTH-WORDLIST CORE Commence formatting a numeric output string. <> ; x1 x2 -- flag FORTH-WORDLIST CORE EXT TRUE iff x1 is not the same bit pattern as x2. = ; x1 x2 -- flag FORTH-WORDLIST CORE TRUE iff x1 is the same bit pattern as x2. > ; n1 n2 -- flag FORTH-WORDLIST CORE TRUE iff signed single n1 is greater than signed single n2. >BODY ; xt -- a-addr FORTH-WORDLIST CORE Convert the execution token of a CREATEd object into its data address. If xt doesn't represent a child of CREATE then THROW a -31. >IN ; -- a-addr FORTH-WORDLIST CORE >NUMBER ; ud1 c-addr1 u1 -- ud2 c-addr2 u2 FORTH-WORDLIST CORE Converts the string at c-addr1 u1 to a double-cell number in the current number base. All characters in the string must be digits. Returns the address and count of unconverted characters remaining in string. >R ; x -- R: -- x FORTH-WORDLIST CORE Move the top data stack item to the top of the return stack. Compile-only. ?DO ; u1 u2 -- FORTH-WORDLIST CORE EXT Consume an outer (u1) and inner (u2) loop limit. If they are not identical, commence the body of the loop. ?DUP ; x -- x x | 0 FORTH-WORDLIST CORE EXT Duplicate the top data stack item iff non-zero. ?STACK ; i*j -- i*j | - NONSTANDARD-WORDLIST -- ABORT if stack has underflowed or overflowed. @ ; a-addr -- x FORTH-WORDLIST CORE Fetch x from the cell at a-addr. [ ; -- FORTH-WORDLIST CORE Enter interpretive state. Compile-time only. ['] ; -- | abort FORTH-WORDLIST CORE At compile time, append the execution token for the following name in the input stream as a literal to the current definition. [CHAR] ; -- Execution: -- char FORTH-WORDLIST CORE At compile time, append a numeric literal to the current definition representing the first character of the next non-blank string in the input stream. ] ; -- FORTH-WORDLIST CORE Enter compile state. ABORT ; -- FORTH-WORDLIST EXCEPTION EXT Compile a -1 THROW. Compilation only. ABORT" ; ccc<"> -- FORTH-WORDLIST EXCEPTION EXT Consume a string terminated by double-quote and compile the string as an error message and a -2 THROW which will have the effect of printing the message ABOUT ; -- NONSTANDARD-WORDLIST --- Prints a revision message followed by a message about Jax4th's Lack of Warranty as free software. ABS ; n -- u FORTH-WORDLIST CORE Return absolute value u of n. ABSTOCODE ; abs-addr -- code-addr SYSTEM-WORDLIST --- Convert a Windows NT address to a Jax4th user-code-space-relative address. ABSTODATA ; abs-addr -- data-addr SYSTEM-WORDLIST --- Convert a Windows NT address to a Jax4th data-space-relative address. ACCEPT ; c-addr +n1 -- +n2 FORTH-WORDLIST CORE Accept up to +n1 characters at c-addr from the user, returning +n2, the count of characters actually received before a possible terminating EOL. AGAIN ; -- FORTH-WORDLIST CORE At compile time, consume a "dest" branch destination from the control flow stack. At runtime, cause a loop back to the corresponding BEGIN. ALIGN ; -- FORTH-WORDLIST CORE Align data space to a boundary corresponding to the alignment needs of the host architecture. ALIGNED ; addr -- a-addr FORTH-WORDLIST CORE If the address addr on the data stack is not aligned, increment it to the next aligned address. ALLOT ; n -- FORTH-WORDLIST CORE Allot n address units in the data space. ALSO ; -- FORTH-WORDLIST SEARCH EXT Dup the top of the wordlist stack. AND ; x1 x2 -- x3 FORTH-WORDLIST CORE x3 is the bitwise AND of x1 and x1. ASCIIZ ; c-addr u -- addr SYSTEM-WORDLIST --- Copies a character string specified by c-addr u as a null-terminated ASCII string into a system buffer whose address is then returned. This system buffer is overwritten each time ASCIIZ is called. Used for NT system calls which don't accept unicode. The buffer is 256 ASCII characters long, and the null terminator will use up one of these character addresses, so the maxiumum value for the argument u is thus 255. NOTE: The address returned by ASCIIZ is a data address, and must be converted via DATATOABS before being passed to a system call. AT-XY ; u1 u2 -- FORTH-WORDLIST FACILITY Move the cursor to the xy position represented by u1 (x) u2 (y). B! ; byte addr -- NONSTANDARD-WORDLIST --- Store a byte to addr. B@ ; addr -- byte NONSTANDARD-WORDLIST --- Fetch a byte from addr. BASE ; a-addr FORTH-WORDLIST CORE Return the address where is stored the numeric conversion base. BEGIN ; -- dest FORTH-WORDLIST CORE BIN ; fam1 -- fam2 FORTH-WORDLIST FILE Set the file mode for binary access. A no-op in Jax4th for Windows NT, just included for source compatibility. BL ; -- char FORTH-WORDLIST CORE Leaves the character for a blank space on the stack. BLK ; -- a-addr FORTH-WORDLIST BLOCK Indicates the current compilation block, or the user input device if 0. BLOCK ; u -- a-addr FORTH-WORDLIST BLOCK Returns the address of the BLOCK buffer containing block u, if available. Will THROW if, for any of a variety of reasons, the requested BLOCK not available. The file being used for BLOCKs is the file whose file-id from OPEN-FILE is placed in the Jax4th variable BLOCK-FILE, q.v. BLOCK-FILE ; -- a-addr NONSTANDARD-WORDLIST --- Variable used to determine the file used for BLOCK I/O. Contains a file-id obtained from OPEN-FILE and placed in BLOCK-FILE by the user. Many files may be kept open and their file-id's stored elsewhere to be swapped in and out of BLOCK-FILE in the course of your operations, should you so desire. However, remember to EMPTY-BUFFERS if you change the file-id in BLOCK-FILE and want to read in a same-numbered BLOCK, or you will get the old BLOCK from the previous file (which will still be valid from the point of view of the BLOCK subsystem, which doesn't watch you swapping file-id's in BLOCK-FILE). For example, here's how to load the example code (if you started Jax4th in the EXAMPLE directory): S" JX4EXAMP.BLK" R/O OPEN-FILE . 0 ok1 BLOCK-FILE ! ok0 1 LOAD BUFFER ; u -- a-addr FORTH-WORDLIST BLOCK Returns the address of the buffer currently assigned to block u, or assigns one to block u if block u is not currently resident. If an UPDATEd buffer is thus reassigned to make room for block u, the UPDATEd block will be written out to mass storage. Block u is not read in by BUFFER; a BLOCK operation is required for that to occur. BYE ; -- FORTH-WORDLIST TOOLS EXT Exit the system, saying goodbye. Does not explicitly close any objects except those opened by Jax4th itself. Clean up after yourself! C! ; c c-addr -- FORTH-WORDLIST CORE Store a character c to a character-aligned address c-addr. C, ; char -- FORTH-WORDLIST CORE Allot one char's worth of data space and store char there. C@ ; c-addr -- char FORTH-WORDLIST CORE char is the char which is located at c-addr. CATCH ; i*x xt -- j*x 0 | i*x n) FORTH-WORDLIST EXCEPTION CATCH a THROW, e.g., : TEST ['] FOO CATCH ; If the return is j*x 0 no THROW was encountered in the execution of FOO otherwise n is the THROW code and the stack is the depth it was before CATCH commenced execution, though not necessarily containing the same items. CATCHFIRSTCATCH ; -- INTERNALS-WORDLIST --- CELL+ ; a-addr1 -- a-addr2 FORTH-WORDLIST CORE Add the number of address units between two adjacent aligned addresses to a-addr1 producing a-addr2. CELLS ; n1 -- n2 FORTH-WORDLIST CORE n2 is n1 times the number of address units in a cell. CHAR ; -- char FORTH-WORDLIST CORE Parses for a char, returning the char value upon the data stack. Discards all text in input stream after char before the next delimiter. CHAR+ ; c-addr1 -- c-addr2 FORTH-WORDLIST CORE Add the number of address units between two adjacent character-aligned addresses to c-addr1 producing c-addr2. CHARS ; n1 -- n2 FORTH-WORDLIST CORE n2 is n1 times the number of address units in a char. CHECKDEPTH ; j*x -- j*x [ 0 | n if stack has changed ] INTERNALS-WORDLIST --- CLOSE-FILE ; fileid -- ior ( == system error if failure, == 0 if success) FORTH-WORDLIST FILE Close the file represented by fileid, returning system-dependent io result ior (0 on success). CMOVE ; c-addr1 c-addr2 u -- FORTH-WORDLIST CORE Move u characters from c-addr1 to c-addr2 starting at low addresses and moving higher. See CMOVE> MOVE CMOVE> ; c-addr1 c-addr2 u -- FORTH-WORDLIST CORE Move u characters from c-addr1 to c-addr2 starting at high addresses and progressing lower. The concept of "C-Move-Right" is that it is responsible for moving data higher in memory when the regions overlap. It handles this by copying data regions end-to-front to avoid replication in a "rightwards" (i.e., higher in memory) overlapping move. See CMOVE MOVE CODETOABS ; code-addr -- abs-addr SYSTEM-WORDLIST --- Convert a user-code-relative address to an absolute address. Such calculations should generally be made at runtime, not at compile time. CODETODATA ; code-addr -- data-addr SYSTEM-WORDLIST --- Convert a user-code-relative address to a user data address. Such calculations should generally be made at runtime, not at compile time. COLD ; -- NONSTANDARD-WORDLIST --- Executed when Jax4th starts up to initialize the system, thn executes the FORTH command line (if any) that accompanied the invocation of Jax4th, then returns the system to QUIT. You may execute this any time, but be aware your original invocation command line will be re-executed. COMPARE ; c-addr1 u1 c-addr2 u2 -- n FORTH-WORDLIST STRING If the strings at c-addr1 u1 and c-addr2 u2 are char-for-char the same, including length, return 0. If u1 and u2 are different, compare up to the length of the shorter string. If the two strings are identical up to the length of the shorter string, return -1 if u1 < u2 and 1 otherwise. If the two strings are not identical up to the length of the shorter, return -1 if the char value of the first nonmatching char c-addr1[n] < c-addr2[n] and return 1 otherwise. COMPILE, ; xt -- FORTH-WORDLIST CORE EXT Append the execution token xt to the current definition. ConsoleMode ; -- a-addr SYSTEM-WORDLIST -- Contains the last Console Mode setting by the system. Applications which change the Console Mode should update this variable. CONSTANT ; x "name" -- FORTH-WORDLIST CORE Create a word named "name" which at runtime returns x on the data stack. COUNT ; c-addr1 -- c-addr2 u FORTH-WORDLIST CORE Convert the counted string a c-addr1 to the address c-addr2 and count u. CR ; -- FORTH-WORDLIST CORE Emit a newline to the current output device. CREATE ; "name" -- FORTH-WORDLIST CORE CREATE a new word "name" which at runtime returns the address of the current end of data allocation. No data space is alloted. See >BODY ALLOT DOES> CREATE-FILE ; c-addr u x1 -- x2 ior (== 0 | system err) FORTH-WORDLIST FILE Create a file whose name is specified by c-addr u with access attributes x1. Return x2 the file identifier and result of either 0 for success or the value returned by the Win32 API call GetLastError() if not successful. See: BIN CLOSE-FILE DELETE-FILE OPEN-FILE R/O R/W READ-FILE REPOSITION-FILE RESIZE-FILE WRITE-FILE D+ ; ud|d1 ud|d2 -- ud|d3 FORTH-WORDLIST DOUBLE ud|d3 is the sum of ud|d1 and ud|d2. D- ; ud|d1 ud|d2 -- ud|d3 FORTH-WORDLIST DOUBLE ud|d3 is the difference of ud|d1 minus ud|d2. D. ; d -- FORTH-WORDLIST DOUBLE Print the signed double d to the current output device in the current number conversion base. D= ; xd1 xd2 -- flag FORTH-WORDLIST DOUBLE Flag is TRUE iff xd1 is bit-for-bit equal to xd2. D>S ; d1 -- n1 FORTH-WORDLIST DOUBLE Convert the signed double-cell number d1 to the signed single n1. Silent truncation occurs if d1 is to large to be represented in n1. D0= ; xd -- flag FORTH-WORDLIST DOUBLE flag is TRUE iff xd is 0.0 DABS ; d -- ud FORTH-WORDLIST DOUBLE Returns the absolute value of d. DATATOABS ; data-addr -- abs-addr SYSTEM-WORDLIST --- Convert a data-relative address to an absolute address. DATATOCODE ; data-addr -- code-addr SYSTEM-WORDLIST --- Convert a data-relative address to a code-relative address. DECIMAL ; -- FORTH-WORDLIST CORE Set the contents of BASE q.v. to 10r10. DEFINITIONS ; -- FORTH-WORDLIST SEARCH Sets the current compilation wordlist to the first wordlist in the search order. See: GET-ORDER ORDER SET-ORDER DELETE-FILE ; c-addr u -- ior (== 0 | system err) FORTH-WORDLIST FILE Delete a file whose name is specified by c-addr u with access attributes x1. Return x2 the file identifier and result of either 0 for success or the value returned by the Win32 API call GetLastError() if not successful. See: BIN CLOSE-FILE CREATE-FILE OPEN-FILE R/O R/W READ-FILE REPOSITION-FILE RESIZE-FILE WRITE-FILE DEPTH ; i*x -- i*x i FORTH-WORDLIST CORE Return on the data stack the depth consumed currently on the data stack prior to the execution of DEPTH. DETOKEN ; user-xt -- code-offset INTERNALS-WORDLIST --- Don't use this. DIGIT ; char n1 -- n2 true | char false NONSTANDARD-WORDLIST --- Return n2 and TRUE on the data stack if n2 is the value of the digit char in base n1. Return the original char and FALSE if it is not a valid digit in base n1. See >NUMBER NUMBER BASE DNEGATE ; d1 -- d2 FORTH-WORDLIST CORE Signed double d2 is the negated value of signed double d1. DO ; u1 u2 -- FORTH-WORDLIST CORE Commences a DO .. LOOP structure. The start index is u2, the termination index is u1. See: ?DO +LOOP LOOP LEAVE UNLOOP DOCONST ; -- x INTERNALS-WORDLIST --- Execution engine for CONSTANT DODLIT ; -- INTERNALS-WORDLIST --- Execution engine for DLITERAL DODO ; u1 u2 -- INTERNALS-WORDLIST --- Execution engine for DO DODOES ; -- x INTERNALS-WORDLIST --- Execution engine for DOES> DODOTQUOTE ; -- INTERNALS-WORDLIST --- Execution engine for ." DOELSE ; -- INTERNALS-WORDLIST --- Execution engine for ELSE DOES> ; -- FORTH-WORDLIST CORE Assign the stream of execution following the DOES> to the most recently CREATEd word. DOIF ; flag -- INTERNALS-WORDLIST --- Execution engine for IF DOKDOTQUOTE ; -- INTERNALS-WORDLIST --- Print strings stored in the kernel exe data section. DOKWORDLIST ; -- a-addr INTERNALS-WORDLIST --- Execution engine for kernel WORDLISTs. DOLIT ; -- x INTERNALS-WORDLIST --- Execution engine for LITERAL DOMARKER ; -- a-addr INTERNALS-WORDLIST --- Execution engine for MARKER words. DOLOOP ; -- INTERNALS-WORDLIST --- Execution engine for LOOP DOPLUSLOOP ; n1 -- INTERNALS-WORDLIST --- Execution engine for +LOOP DOQDO ; u1 u2 -- INTERNALS-WORDLIST --- Execution engine for ?DO DOSQUOTE ; -- c-addr u INTERNALS-WORDLIST --- Execution engine for S" DOUNTIL ; flag -- INTERNALS-WORDLIST --- Execution engine for UNTIL DOUNTILNOT ; flag -- INTERNALS-WORDLIST --- Execution engine for an anonymous function used in the kernel DOWORDLIST ; -- a-addr INTERNALS-WORDLIST --- Execution engine for WORDLISTs defined by the user. DP ; -- a-addr INTERNALS-WORDLIST --- Variable containing the data pointer. DPL ; -- a-addr INTERNALS-WORDLIST --- Variable containing the position of the decimal point in the most-recently parsed number entry. DROP ; x -- FORTH-WORDLIST CORE Discard top data stack item. DUM/MOD ; d1 n1 -- n2 d2 NONSTANDARD-WORDLIST --- Divides double d1 by n1 leaving double quotient d2 and modulus n2. DUMP ; a-addr u -- FORTH-WORDLIST TOOLS Formatted hex dump of memory starting from at least a-addr and proceeding for at least u addresses. In Jax4th for Windows NT, the display is by unicode characters, and Intel little-endian addresses are swapped in pairs in the display to make character reading easier. DUMPLINE ; a-addr1 -- a-addr2 DUP ; x -- x x FORTH-WORDLIST CORE Duplicate top data stack item. EKEY ; -- u FORTH-WORDLIST FACILITY EXT Return the value of the next keypress event. The 32-bit value returned by Jax4th encoded as follows: Bits 0-15: The Unicode value (if any) of the key pressed. Bits 16-31: The Windows Virtual Key Code of the key pressed. For example, pressing the 'A' key on my keyboard with no shift or capslock results in the hex value 00410061 where 0041 is the Windows Virtual Key Code and 0061 ('a') is the Unicode value of the character resulting. Pressing the <PgUp> key results in 00210000, a VKC of 0021 and no Unicode character assigned. ELSE ; orig1 -- orig2 FORTH-WORDLIST CORE Indicates the alternate execution branch when an IF test fails. EMIT ; char -- FORTH-WORDLIST CORE Send the character char to the current output device. EMPTY-BUFFERS ; -- FORTH-WORDLIST BLOCK Discard the contents of all disk buffers used by the BLOCK facility and mark them as un-UPDATEd. ENABLE_ECHO_INPUT ; -- x SYSTEM-WORDLIST Constant for SetConsoleMode. ENABLE_LINE_INPUT ; -- x SYSTEM-WORDLIST Constant for SetConsoleMode. ENABLE_MOUSE_INPUT ; -- x SYSTEM-WORDLIST Constant for SetConsoleMode. ENABLE_PROCESSED_INPUT ; -- x SYSTEM-WORDLIST Constant for SetConsoleMode. ENABLE_WINDOW_INPUT ; -- x SYSTEM-WORDLIST Constant for SetConsoleMode. EVALUATE ; i*x c-addr u -- j*x FORTH-WORDLIST CORE, BLOCK Interpret the string specified by c-addr u. SOURCE-ID is -1 while this is taking place. ENVIRONMENT? ; c-addr u -- false | i*x true FORTH-WORDLIST CORE Answer the environmental query specified by c-addr u and return TRUE or answer FALSE if the answer isn't known. Jax4th for Windows NT can't answer any environemental queries until some of these answers are loaded, e.g., in UTILS\UTILS.UTF. EXECUTE ; i*x xt -- j*x FORTH-WORDLIST CORE Execute the word whose execution token is on top of the data stack. EXETOLINK ; a-addr1 -- a-addr2 INTERNALS-WORDLIST Convert a data-relative address of an execution field to the data- relative address of the corresponding link field. EXETONAME ; a-addr -- c-addr INTERNALS-WORDLIST Convert a data-relative address of an execution field to the data- relative address of the corresponding name field. EXIT ; -- R: nest-sys -- FORTH-WORDLIST CORE Unnest from the currently executing definition. FALSE ; -- flag FORTH-WORDLIST CORE EXT Returns 0 on the data stack. FERROR ; -- a-addr NONSTANDARD-WORDLIST Variable containing the last error reported by INCLUDE-FILE, if any. FILE-POSITION ; fileid -- ud ior (0= success , nz== last error FORTH-WORDLIST FILE Return the current offset in the file represented by fileid at which or from which the next write or read will take place. This is a deferred word and is vectored at startup to the Unicode version FILE-POSITIONW in which ud is a number of characters. See REPOSITION-FILE FILE-POSITIONA ; fileid -- ud ior (0= success , nz== last error NONSTANDARD-WORDLIST Ascii version of FILE-POSITION. ud is bytes. FILE-POSITIONW ; fileid -- ud ior (0= success , nz== last error NONSTANDARD-WORDLIST Unicode version of FILE-POSITION. ud is widechars. FILE-SIZE ; fileid -- ud ior FORTH-WORDLIST FILE If ior returns zero, ud is the size of the file represented by fileid. This is a deferred word and is vectored at startup to the Unicode version FILE-SIZEW. See FILE-POSITION. FILE-SIZEA ; fileid -- ud ior NONSTANDARD-WORDLIST Ascii version of FILE-SIZE. ud is bytes. FILE-SIZEW ; fileid -- ud ior NONSTANDARD-WORDLIST Unicode version of FILE-SIZE. ud is widechars. FILL ; c-addr u char -- FORTH-WORDLIST CORE Fill the string specified by c-addr u with char. FIND ; ( c-addr -- c-addr 0 | xt 1 | xt -1 ) FORTH-WORDLIST Find the name represented by the counted string at c-addr in the current dictionary search order. Return either the same c-addr and 0 if not found, or the execution token xt and 1 if the word is IMMEDIATE and -1 if it is not. FIRSTCATCH ; -- R: -- catch-sys INTERNALS-WORDLIST Generate the default CATCH frame the system uses to field all otherwise uncaught THROWS. FLUSH ; -- FORTH-WORDLIST BLOCK Write all UPDATEd BLOCK buffers to disk and mark them unUPDATEd. FM/MOD ; d1 n1 -- n2 n3 FORTH-WORDLIST CORE Return the result of floored division of signed single n1 upon signed double d1 as quotient n3 and modulus n2. FORTH ; -- FORTH-WORDLIST SEARCH EXT Makes the FORTH-WORDLIST the first wordlist in the dictionary search order without deepening that search order. See also: FORTH-WORDLIST FORTH-WORDLIST ; -- wid FORTH-WORDLIST SEARCH Returns the wid representing the FORTH-WORDLIST. See also: FORTH WORDLIST FreeLibrary ; hLibModule -- SYSTEM-WORDLIST Frees the library module represendted by hLibModule which was previously opened by the user via the Jax4th for NT word LoadLibraryEx (q.v.). GET-CURRENT ; -- wid FORTH-WORDLIST SEARCH Returns the wid representing the current compilation wordlist. GET-ORDER ; ( -- wid1 .. widn n) FORTH-WORDLIST SEARCH Returns the wordlist id's for all wordlists in the dictionary search order topped with the number n of wordlists in the order (hence, the number of wid's below n on the stack). GETCOMMANDLINE ; -- c-addr u SYSTEM-WORDLIST Returns Forth address and count of the command line with which Jax4th was invoked. GetConsoleMode ; -- LastErr | TRUE SYSTEM-WORDLIST Instances the ConsoleMode variable and returns TRUE for success or the error code returned by Win32's GetLastError() API if failed. GetProcAddress ; [lpszProc | ordinal] hModule -- abs-addr | nil SYSTEM-WORDLIST Given the absolute address of a null-terminated ASCII string (See: ASCIIZ) and the handle to a library module, performs the GetProcAddress call and returns either the absolute address of the named procedure or 0 indicating failure, in which case the Forth variable LastError will hold the error code (if subsequently examined before any console I/O takes place). Alternatively, the first parameter to this call may be the ordinal number of the desired routine, in which case the upper 16 bits of such a number must be zeroes (0). Does no sanity checking on its parameters. See: ASCIIZ FreeLibrary LoadLibraryEx SYSCALL HEADER ; c-addr u -- INTERNALS-WORDLIST Creates a name header, not linked in, from the string specified by c-addr u. HERE ; -- addr FORTH-WORDLIST CORE Returns the next ALLOTable address in data space. HEX ; -- FORTH-WORDLIST CORE Changes number conversion base to 16 (hexadecimal). HLD ; a-addr NONSTANDARD-WORDLIST Variable used by HOLD HOLD ; char -- FORTH-WORDLIST CORE Store char at the beginning address of the pictured numeric output string and decrement the pointer thereto so that the next HOLD operation will do the same. I ; -- n|u FORTH-WORDLIST CORE Returns the current inner loop index of a DO .. LOOP-type construction. IF ; flag -- FORTH-WORDLIST CORE At compile time, leaves an "origin" on the control flow stack. At runtime, consumes a flag and branches to the corresponding ELSE or THEN (if no ELSE) iff the flag is FALSE. IMMEDIATE ; -- FORTH-WORDLIST CORE Renders the most recently defined colon definition IMMEDIATE, that is, one which executes at compile time, rather than having its execution appended to the definition under construction. IMMEDIATE must be executed after the semicolon (";") of the colon definition in question, and before any other additions or alterations to the dictionary are made. INCLUDE-FILE ; -- i*x fileid -- j*x FORTH-WORDLIST FILE Interpret the entire file represented by fileid. The user is responsible for obtaining fileid via a call to OPEN-FILE, etc. If for any reason the interpretation ABORTs or THROWs, there is no guarantee about the state of the file pointer: it's best to close the file and re-open it before reloading. INCLUDED ; -- i*x c-addr u -- j*x FORTH-WORDLIST FILE Attempt to open and unterpret the entire file whose name is represented by c-addr u. If for any reason the interpretation ABORTs or THROWs, there is no guarantee about the state of the file pointer. INTERNALS-WORDLIST ; -- wid FORTH-WORDLIST Wordlist containing many implementation details of Jax4th. INTERPRET ; ( --) INTERNALS-WORDLIST Interpret the input stream. INVALIDBLOCK ; u -- flag INTERNALS-WORDLIST flag is TRUE if u is not a valid BLOCK number in the file whose handle is stored in BLOCK-FILE. If BLOCK- FILE's contents do not represent a valid file handle, perform file i/o exception THROW -37. Used by BLOCK and REFILL. INVERT ; x1 -- x2 FORTH-WORDLIST CORE Reverses all bits of x1 yielding x2. J ; -- n|u FORTH-WORDLIST CORE Sets compilation state. KEY ; -- char FORTH-WORDLIST CORE Returns the next keypress from the standard character set. KEY? ; -- flag FORTH-WORDLIST FACILITY Returns TRUE if a keypress is waiting in the range of 1Bh and above, and also carriage return 0Dh. LastError ; -- a-addr SYSTEM-WORDLIST Holds last error reported from I/O operation via Windows NT. LEAVE ; -- R: loop-sys -- FORTH-WORDLIST CORE Clean off the loop stack and immediately LEAVE a loop. LINKIT ; -- INTERNALS-WORDLIST Link the current definition. LINKTOEXE ; a-addr1 -- a-addr2 INTERNALS-WORDLIST Convert a data-relative address of a link field to the data- relative address of the corresponding execution field. LINKTONAME ; a-addr -- c-addr INTERNALS-WORDLIST Convert a data-relative address of a link field to the data- relative address of the corresponding name field. LIST ; u -- FORTH-WORDLIST BLOCK EXT Display BLOCK u. A Forth file i/o THROW -37 will occur if the value in BLOCK-FILE is zero (0). A Block Read THROW -33 will occur if the file handle in BLOCK-FILE is invalid. A Block Write THROW -34 will occur if an updated buffer was waiting to be written but the operation failed. An invalid BLOCK number THROW -35 will occur if u is not a valid BLOCK number in the BLOCK-FILE file. LITERAL ; x -- FORTH-WORDLIST CORE Compile-only. Append the numeric literal x to the current definition. LOAD ; i*x u -- j*x FORTH-WORDLIST CORE Interpret BLOCK number u. A Forth file i/o THROW -37 will occur if the value in BLOCK-FILE is zero (0). A Block Read THROW -33 will occur if the file handle in BLOCK-FILE is invalid. A Block Write THROW -34 will occur if an updated buffer was waiting to be written but the operation failed. An invalid BLOCK number THROW -35 will occur if u is not a valid BLOCK number in the BLOCK-FILE file. An attempt to perform 0 LOAD will invoke QUIT. LoadLibraryEx ; dwFlags 0 lpszLibFile -- hModule | 0 SYSTEM-WORDLIST Calls NT system to open the named module specified by the null-terminated Unicode string which is the third parameter to this call. All S" strings are null-terminated, so their count may be dropped and the remaining address passed to DATATOABS to provide this parameter. The other two parameters are, in order, the flag indicating whether the initialization routine should be called for the library, and a reserved 0 parameter. See the Windows NT SDK for further information on the call itself. Does no sanity checking on its parameters. The return is either the handle of the desired library module or a NULL for error, in which case the Forth variable LastError will hold the error code (if subsequently examined before any console I/O takes place). See: DATATOABS FreeLibrary S" LOGIN ; -- INTERNALS-WORDLIST Message seen at startup of Jax4th LOGOFF ; -- INTERNALS-WORDLIST Message seen on exit from Jax4th. LOOP ; dest -- FORTH-WORDLIST CORE Resolves the backwards branch of a DO or ?DO. LSHIFT ; x1 u -- x2 FORTH-WORDLIST CORE Left-shifts x1 by u places leaving x2. M* ; n1 n2 -- d FORTH-WORDLIST CORE Multiplies two signed singles returning a signed double. MAKEDOES ; xt -- INTERNALS-WORDLIST Lays down the execution for a DOES> word. Don't use this word. MAKETOKEN ; code-offset -- user-xt INTERNALS-WORDLIST Creates an execution token from an offset. Don't use this word. MARKER ; "name" -- FORTH-WORDLIST CORE EXT Create a "forgettable" word which, when executed, restores the dictionary to the precise state it was in before the MARKER word was defined. Also unallots all data space that was alloted prior to the MARKER word being defined, though this effect is not guaranteed in the Standard. No checking for outstanding references to deleted structures, e.g., disappearing wordlists in the search order, is provided. MAX ; n1 n2 -- n3 FORTH-WORDLIST CORE n3 is the signed maximum of n1 n2. MIN ; n1 n2 -- n3 FORTH-WORDLIST CORE n3 is the signed minimum of n1 n2. MOVE ; addr1 addr2 u -- FORTH-WORDLIST CORE Move the contents of u address units from the region starting at addr1 to the region starting at addr2. Copy in the correct order to prevent replication in case of overlapping memory regions. NAMEWORDLIST ; c-addr u -- wid NONSTANDARD-WORDLIST Create a wordlist whose name will show in the ORDER dump of wordlist names. The name is specified by c-addr u. NAMEWORDLIST is a convenience and not a Standard feature, nor are NAMEWORDLIST constructions non-standard, unless a program depends on their name being usable. Think of it as a debugging convenience. Named wordlists created by NAMEWORDLIST are no different in their internal structure than a wordlist created by WORDLIST (q.v.). The only difference is that a NAMEWORDLIST has a regular Forth name header and a WORDLIST is created with a header that tells the Jax4th interpreter that it is a "headerless" item in the dictionary. NAMETOEXE ; c-addr -- a-addr INTERNALS-WORDLIST Convert a data-relative address of a name field to the data- relative address of the corresponding execution field. NAMETOLINK ; c-addr -- a-addr INTERNALS-WORDLIST Convert a data-relative address of a name field to the data- relative address of the corresponding link field. NEGATE ; n1 -- n2 FORTH-WORDLIST CORE n2 is n1 negated. NEST ; -- R: -- sys SYSTEM-WORDLIST This is the nesting engine of the Forth interpreter. Don't use this word! NIP ; x1 x2 -- x2 FORTH-WORDLIST CORE EXT Remove the second data stack entry. NONSTANDARD-WORDLIST ; -- wid Wordlist containing nonstandard but generally useful Jax4th words. NOOP ; -- Does nothing but waste a few CPU cycles. NUMBER ; c-addr1 u1 -- d TRUE | x x FALSE Converts the string at c-addr1 u1 to a double-cell number in the current number base. Correctly handles sign and embedded decimal point. Returns false if unconvertible characters were encountered. okPrompt ; -- INTERNALS-WORDLIST Guess what this does. ONLY ; -- FORTH-WORDLIST SEARCH EXT Sets the minimum search order, consisting in the case of Jax4th of the FORTH-WORDLIST alone. OPEN-FILE ; c-addr u x1 -- x2 ior (== 0 | system err) FORTH-WORDLIST FILE OR ; x1 x2 -- x3 FORTH-WORDLIST x3 is the bitwise OR of x1 and x2. ORDER ; -- FORTH-WORDLIST Displays the dictionary search order and the compilation wordlist. OVER ; x1 x2 -- x1 x2 x1 FORTH-WORDLIST Copies data stack item x1 to top of stack. PAD ; -- c-addr FORTH-WORDLIST Returns the character-aligned address of a scratch buffer. No system words use this buffer, but its persistence is not guaranteed across dictionary operations. PAGE ; -- FORTH-WORDLIST FACILITY Advance the output device by one "page", e.g., clear the screen most of the time. PARSE ; ( char "ccc<char>" -- c-addr u) FORTH-WORDLIST PICK ; xu .. x1 x0 u -- xu .. x1 x0 xu FORTH-WORDLIST CORE EXT Copy the u'th data stack item to top of data stack. PLACE ; c-addr1 u c-addr2 NONSTANDARD-WORDLIST An old favorite. Copy the counted string specified by c-addr1 u to c-addr2. POSTPONE ; "name" -- FORTH-WORDLIST CORE Append the compilation semantics of name to the current definition. PREVIOUS ; -- FORTH-WORDLIST SEARCH EXT Reduce the length of the search order discarding the first wordlist in the order. QUIT ; ( --) ( R: i*x --) FORTH-WORDLIST CORE Return to the Forth interpreter, having cleared the return stack. R> ; -- x R: x -- FORTH-WORDLIST CORE Remove x from the top of the return stack and place it on the data stack. R@ ; -- x R: x -- x FORTH-WORDLIST CORE Copy the top element of the return stack to the data stack. R/O ; -- x FORTH-WORDLIST FILE Indicates to certain FILE words that the access mode is read-only. R/W ; -- x FORTH-WORDLIST FILE Indicates to certain FILE words that the access mode is read-write. READ-FILE ; c-addr u1 fileid -- u2 ior (== 0 | system err) FORTH-WORDLIST FILE Read u1 units to c-addr from file described by fileid. This is a deferred word and is vectored at startup to the Unicode version READ-FILEW. See WRITE-FILE READ-FILEA ; c-addr u1 fileid -- u2 ior (== 0 | system err) NONSTANDARD-WORDLIST ASCII version of READ-FILE. READ-FILEW ; c-addr u1 fileid -- u2 ior (== 0 | system err) NONSTANDARD-WORDLIST Unicode version of READ-FILE. RECURSE ; -- FORTH-WORDLIST CORE EXT Append to the current definition under construction a runtime call to the head of that same definition. For example, the definition : TILL-ZERO ( n -- 0) DUP 0> IF 1- RECURSE ELSE DUP 0< IF 1+ RECURSE THEN THEN ; will turn any number to zero, providing the return stack doesn't overflow first with the level of nesting (one entry per recursive call). REFILL ; -- flag FORTH-WORDLIST CORE, BLOCK Get another input buffer full of input, return TRUE for success and 0 for failure. If BLK is zero (0) this is a request for another line of input from the user. If BLK is non-zero, REFILL effectively means BLK @ 1+ LOAD. RELOAD ; "ccc< >" -- ior SYSTEM-WORDLIST Parse a filename and open it as a saved user image and reload it. NOTE!!! Use only on the command shell command line when invoking Jax4th, because RELOAD continues parsing the input stream. If you use it from within the Forth interpreter, there will be "stuff" left in the restored terminal input buffer, which probably won't be what you meant to interpret. For reloading a user image from within Jax4th itself, use RELOAD-FILE or RELOADED, q.v. RELOAD-FILE ; i*x fid -- j*x u ior SYSTEM-WORDLIST Reload the file specificed by fid as a user image. This will be the last word parsed and executed on the Forth input line in which it is found interpretively, as images are saved with the input specification set to an empty TIB. The returns from RELOAD-FILE are the bytes (not chars) read in the file read operation, and the ioresult from the file read operation. To reload an image and then execute a command, compile RELOAD-FILE into a definition and then execute that definition. See also: RELOAD RELOADED RELOADED ; c-addr u -- u ior1 ior2 SYSTEM-WORDLIST Reload the file whose name is specified by c-addr u as a user image. This will be the last word parsed and executed on the Forth input line in which it is found interpretively, as images are saved with the input specification set to an empty TIB. The returns from RELOADED are the bytes (not chars) read in the file read operation, the ioresult from the file read operation, and ioresult from the file close operation. To reload an image and then execute a command, compile RELOADED into a definition and then execute that definition. See also: RELOAD-FILE RELOAD REPEAT ; orig dest -- FORTH-WORDLIST CORE Consume an orig and dest from the control flow stack and use them to calculate and fix up the information provided and required by the providers of orig and dest. dest is the point to which the REPEAT will branch back when encountered at runtime. orig is the information for the position and which branch information for the execution cell beyond the REPEAT is located for a forward-branching test. See: AGAIN BEGIN UNTIL WHILE REPOSITION-FILE ; ud fileid -- ior ( == 0 | system err) FORTH-WORDLIST FILE Move file pointer to position ud in file described by fileid. This is a deferred word and is vectored at startup to the Unicode version REPOSITION-FILEW. See FILE-POSITION REPOSITION-FILEA ; ud fileid -- ior ( == 0 | system err) NONSTANDARD-WORDLIST ASCII version of REPOSITION-FILE. REPOSITION-FILEW ; ud fileid -- ior ( == 0 | system err) NONSTANDARD-WORDLIST Unicode version of REPOSITION-FILE. RESIZE-FILE ; ud fileid -- ior ( == 0 | system err) FORTH-WORLDIST FILE Resize the file represented by fileid to the size ud. The contents of any previously unwritten extent if the file size is thus increased are undefined. This is a deferred word and is vectored at startup to the Unicode version REPOSITION-FILEW. See FILE-SIZE RESIZE-FILEA ; ud fileid -- ior ( == 0 | system err) NONSTANDARD-WORDLIST ASCII version of RESIZE-FILE. RESIZE-FILEW ; ud fileid -- ior ( == 0 | system err) NONSTANDARD-WORDLIST Unicode version of RESIZE-FILE. RESTORE-CON ; x1 .. xn -- INTERNALS-WORDLIST Restore certain Console session items saved by SAVE-CON, q.v. RESTORE-INPUT ; xn .. x1 n -- FORTH-WORDLIST CORE EXT Restore the input specification from the items deposited on the data stack by SAVE-INPUT, q.v. ROT ; x1 x2 x3 -- x2 x3 x1 FORTH-WORDLIST CORE Rotate third-on-data-stack to first-on-data-stack. RP! ; abs-addr -- NONSTANDARD-WORDLIST Set the value of the return stack pointer to abs-addr. RP@ ; -- abs-addr NONSTANDARD-WORDLIST Get the value of the return-stack pointer. RSHIFT ; x1 u -- x2 FORTH-WORDLIST CORE Shift x1 right by u places, filling in zeroes to the left. S" ; Interp: "ccc<"> -- c-addr u Compile: -- "ccc<"> Execute: -- c-addr u FORTH-WORDLIST S" parses up to the next delimiting double-quote character. If interpreting, S" places the result in a temporary buffer and places the string address and its count on the stack. The buffer itself is overwritten by the next occurence of an interpretive S". If compiling, S" aligns data space, then allots data space and moves the parsed string into that alloted space, then appends to the current definition the code to place the address and count of the string on the stack at runtime. Not included in the count in either case is a null terminator appended to make interfacing with the NT system easier. The size of the temporary buffer used for interpretive S" is 256 characters. Since one character is used for the string count, and one character is used for the null pad, the maximum string length for interpretive S" is 254 characters. If this count is exceeded, the buffer will overflow silently into data space, with undefined results. The size of a compiled S" string is limited to (2^16)-1 characters, or the size of remaining data space, whichever is less. If the string exceeds this size, the results are undefined. S>D ; n1 -- d1 FORTH-WORDLIST CORE Convert signed single n1 to signed double d1 on the data stack. SAVE-BUFFERS ; -- FORTH-WORDLIST BLOCK Write all UPDATEd block buffers to disk. A Forth file i/o THROW -37 will occur if the value in BLOCK-FILE is zero (0). A Block Read THROW -33 will occur if the file handle in BLOCK-FILE is invalid. A Block Write THROW -34 will occur if an updated buffer was waiting to be written but the operation failed. An invalid BLOCK number THROW -35 will occur if u is not a valid BLOCK number in the BLOCK-FILE file. SAVE-CON ; -- x1 .. xn INTERNALS-WORDLIST Save certain Console session items for later restore by RESTORE-CON, q.v. SAVE-FORTH ; -- 0|ior NONSTANDARD-WORDLIST Brings up a requester for a file name to save the current image of the user dictionary and data space. Returns 0 if successful, or an I/O error code ior if failed. If ior is non-zero and matches the value of LastError (if read in an atomic operation with SAVE-FORTH ... LastError is altered by Console I/O), then ior is a return from the file open or write operation. If ior doesn't match LastError read in an atomic operation with SAVE-FORTH then ior is the return from GetCmdDlgExtendedError() and the file requester dialog failed. SAVE-FORTH or any word containing SAVE-FORTH is the last word parsed on the line in which it is encountered by the interpreter. If any processing is desired at the same time as SAVE-FORTH then SAVE-FORTH should be compiled into a higher-level word. See: RELOAD RELOAD-FILE RELOADED SAVE-INPUT ; -- xn .. x1 n FORTH-WORDLIST CORE EXT Save items representing the current input specification on the stack topped by the number of items thus saved. Input specification can be restored by RESTORE-INPUT, q.v. SAVEDEPTH ; i*x -- i*x INTERNALS-WORDLIST Stores internally the depth of the data stack. SCAN ; ( c-addr1 u1 char --- c-addr2 u2) NONSTANDARD-WORDLIST Seek char in the string specified by c-addr1 u1 and return c-addr2 u2 specifying the string remaining starting with the first occurence of the character. SCR ; -- a-addr FORTH-WORDLIST BLOCK EXT Variable holding the last LISTed block file screen. SEARCH-WORDLIST ; c-addr u wid -- 0 | xt 1 | xt -1) FORTH-WORDLIST SEARCH Search for c-addr u as a name in wordlist wid, returning zero (0) if not found, or xt the execution token for the word if found with 1 if IMMEDIATE and -1 if not. SET-CURRENT ; wid -- FORTH-WORDLIST SEARCH Make the wordlist represented by wid the current compilation wordlist. SET-ORDER ; wid1 .. widn n -- FORTH-WORDLIST SEARCH Reset the dictionary search order to the order specified by wid1 thru widn for a search-order length of n. SetConsoleMode ; x -- LastErr | TRUE SYSTEM-WORDLIST Set the NT console mode of Jax4th to the value specified by x. See: The constants above whose names start with ENABLE_ SIGN ; n -- FORTH-WORDLIST Within a <# ... #> expression, prepend a minus sign to the current pictured numeric output string if n is negative. SKIP ; ( c-addr1 u1 char --- c-addr2 u2) NONSTANDARD-WORDLIST Index through c-addr1 u1 until the first character not matching char is found. Return the remaining string. SLITERAL ; c-addr1 u Execution: -- c-addr2 u FORTH-WORDLIST STRING SM/REM ; d1 n1 -- n2 n3 FORTH-WORDLIST CORE Return the result of symmetrical division of signed single n1 upon signed double d1 as quotient n3 and remainder n2. SOURCE ; -- c-addr u FORTH-WORDLIST CORE Return the address and count of the current input stream. SOURCE-ID ; -- a-addr FORTH-WORDLIST CORE, FILE Returns 0 if interpreting, -1 if EVALUATEing and file-id if interpreting from a FILE. SP! ; abs-addr -- NONSTANDARD-WORDLIST Set the data stack poitner to abs-addr. SP0 ; -- a-addr NONSTANDARD-WORDLIST Variable containing the initial value of the data stack pointer. SP@ ; -- abs-addr NONSTANDARD-WORDLIST Return the current contents of the data stack pointer. SPACE ; -- FORTH-WORDLIST CORE Emit one (1) space to the current output device. SPACES ; n -- FORTH-WORDLIST CORE Emit n spaces to the current output device. STATE ; -- a-addr FORTH-WORDLIST CORE Variable containing TRUE if compiling, FALSE otherwise. STATEABORT ; -- INTERNALS-WORDLIST THROW -14 (interpreting a compile-only word). StdErr ; -- a-addr SYSTEM-WORDLIST Holds the NT console handle for Jax4th's standard err. StdIn ; -- a-addr SYSTEM-WORDLIST Holds the NT console handle for Jax4th's standard in. StdOut ; -- a-addr SYSTEM-WORDLIST Holds the NT console handle for Jax4th's standard out. SYSTEM-WORDLIST ; -- wid FORTH-WORDLIST Wordlist of words used to access the host system. SWAP ; x1 x2 -- x2 x1 FORTH-WORDLIST CORE Exchange top two data stack items. SYSCALL ; abs-addr -- edx eax Performs a call to abs-addr and returns, pushing EDX and EAX which are used by DLL calls for returns. Does no sanity checking on stack or on abs-addr. THEN ; -- FORTH-WORDLIST At compile time, consume an "origin" from the control-flow stack. At runtime, do nothing but serve as the exit point from a control flow construct in which THEN is appropriate. THROW ; k*x n -- k*x | i*x n FORTH-WORDLIST EXCEPTION Toss an exception to the sytactically enclosing CATCH frame, or lacking one, to the default Forth exeception frame. THRU ; i*x u1 u2 -- j*x FORTH-WORDLIST BLOCK EXT LOAD BLOCKs u1 through u2 one at a time. TIB ; -- c-addr FORTH-WORDLIST CORE EXT Return the address of the terminal input buffer. TOKENTODATA ; linkt|xt -- a-addr IMPLEMENTATION-WORDLIST Convert an execution or link token to its corresponding data-relative address. TRUE ; -- flag FORTH-WORDLIST CORE EXT All bits set. TUCK ; x1 x2 -- x2 x1 x2 FORTH-WORDLIST CORE EXT Copy the top data stack item under the second data stack item. TYPE ; c-addr u -- FORTH-WORDLIST CORE Display the character string represented by c-addr u to the current output device. U. ; u -- FORTH-WORDLIST CORE Display the unsigned number u on the current output device. U.R ; u n -- NONSTANDARD-WORDLIST Display the unsigned number u on the current output device right-justified to n places. U< ; u1 u2 -- flag FORTH-WORDLIST CORE True if unsigned u1 is less than unsigned u2. UD*U ; ud1 u1 -- ud2 NONSTANDARD-WORDLIST Multiply unsigned double ud1 by unsigned single u2 with the result being unsigned double u2. UD. ; ud -- NONSTANDARD-WORDLIST Display the unsigned double number ud on the current output device. UD.R ; ud n -- NONSTANDARD-WORDLIST Display the unsigned double number ud on the current output device right-justified to n places. UD< ; ud1 ud2 -- flag NONSTANDARD-WORDLIST flag is TRUE iff ud2 is greater unsigned than ud1. UDMIN ; ud1 ud2 -- ud1|ud2 NONSTANDARD-WORDLIST Returns the minimum of two unsigned double numbers. UM* ; u1 u2 -- ud FORTH-WORDLIST CORE Unsigned multiply of u1 by u2 leaves unsigned double ud. UM/MOD ; ud u1 -- u2 u3 FORTH-WORDLIST CORE u3 is the quotient and u2 the modulus of unsigned division performed on ud2 by u1. UNFOUND ; -- INTERNALS-WORDLIST Error handler for a word not found in a dictionary search during interpretation or compilation. UNICODE ; b-addr u -- addr Copies an ASCII string specified by c-addr u as a null-terminated UNICODE string into a system buffer whose address is then returned. This system buffer is overwritten each time ASCIIZ is called. The buffer is 128 Unicode characters long, and the null terminator will use up one of these character addresses, so the maxiumum value for the argument u is thus 127. UNLOOP ; -- R: loop-sys -- FORTH-WORDLIST CORE Clear the loop stack of the data for the innermost enclosing loop. UNNEST ; -- x R: nest-sys -- NONSTANDARD-WORDLIST Same as EXIT. UNRESOLVED ; -- INTERNALS-WORDLIST Error handler for a branch left unresolved during compilation. UNTIL ; flag -- FORTH-WORDLIST CORE Branches back to the syntactically corresponding BEGIN if flag is FALSE, procedes onwards if flag is TRUE. UPDATE ; -- FORTH-WORDLIST BLOCK Cause the most-recently-accessed BLOCK buffer to be marked as updated, causing it to be written to disk on the next SAVE-BUFFERS or FLUSH operation, or when the buffer is reused. USERTOKEN? ; xt -- flag INTERNALS-WORDLIST Returns TRUE if xt is an execution token of a type matching those for a user-defined word. VARIABLE ; "name" -- FORTH-WORDLIST CORE Create a variable named "name" which at runtime will push its data address on the data stack. W/O ; -- x FORTH-WORDLIST Used with OPEN-FILE q.v. to signify write-only access. WORDLIST ; -- wid FORTH-WORDLIST SEARCH Create a wordlist to which dictionary entries may be appended, and which may be placed in the search order. Jax4th for Windows NT also provides a mechanism whereby named wordlists may be created, for user convenience, although this is not a standard feature. Here we will discuss the internal structure of a wordlist in Jax4th. These are not standard issues: this is merely the way Jax4th implements wordlists. The fact that the wordlist we will examine for an example happens to be a named wordlist is not important in this context. First of all, a wordslist's "wid" (wordlist identifier, the stack entry representing a wordlist) is a data address representing an address in user code space. By placing the wid of FORTH-WORDLIST (a Standard wordlist) on the stack and doing a dump some address units back, we (coincidentally) find the header in the dictionary and all the rest of the information stored for the FORTH-WORDLIST except the pointer to the last entry in the wordlist. HEX ok FORTH-WORDLIST 20 - 20 DUMP Address 0100 0302 0504 0706 0908 0B0A 0D0C 0F0E Unicode 002C2210 FFFF 000E 0046 004F 0052 0054 0048 002D .FORTH- \ ^count ^name field 002C2220 0057 004F 0052 0044 004C 0049 0053 0054 WORDLIST \ ^rest of name field (remember this is unicode) 002C2230 1118 0040 0038 0000 0000 0000 37AC 0040 .@8...¼@ \ ^execution ^pointer ^back ^link pointer to next \ engine to thread pointer word in dictionary to previous wordlist ok (The actual addresses are specific to the revision of Jax4th from which the example was taken.) We see that in the example, FORTH-WORDLIST has its name count starting at 2c2210 (the FFFF is a marker in a Jax4th count field). The count is Oe (14) characters: FORTH-WORDLIST. The execution engine for FORTH-WORDLIST has a token of 00401118 (remember, this is Intel architecture). After the execution engine is a pointer to data space where the thread pointer is located. The thread pointer points to the most recently defined word in this wordlist. Following the thread pointer is a back pointer to the previous wordlist which had been the last defined wordlist at the time that FORTH-WORDLIST was defined. In this case that pointer is 00000000 since the FORTH-WORDLIST was the first wordlist defined. Had there been a link there, it would have been an absolute address of the wordlist link pointer in the previous wordlist. After that, we see that the DUMP display includes coincidentally the link pointer for the next entry in the dictionary, whatever that happens to be, but this has no signficance to our discussion of wordlists or the FORTH-WORDLIST. Named wordlists created by NAMEWORDLIST (q.v.) are no different in their internal structure than a wordlist created by WORDLIST. The only difference is that a NAMEWORDLIST has a regular Forth name header and a WORDLIST is created with a header that tells the Jax4th interpreter that it is a "headerless" item in the dictionary. WORDLISTS ; -- Displays all wordlists in the system, both system and user wordlists. In the example below, there are four (4) system wordlists, one anonymous user wordlist (the "normal" kind of wordlist) and a NAMEWORDLIST called ARFARF. WORDLISTS Wordlists: FFFF0030 named ARFARF FFFF0010 named 2C22D8 named SYSTEM-WORDLIST 2C22A4 named NONSTANDARD-WORDLIST 2C2268 named INTERNALS-WORDLIST 2C2230 named FORTH-WORDLIST ok WHILE ; flag -- FORTH-WORDLIST CORE At compile time, take a "dest" and replace it with an "orig dest" pair on the control flow stack for later resolution, e.g., by REPEAT (q.v.). At runtime, consume a flag and iff false, branch away just past corresponding REPEAT. WITHIN ; n|u1 n|u2 n|u3 -- flag FORTH-WORDLIST CORE EXT WORD ; ( char "ccc<char>" -- c-addr) FORTH-WORDLIST CORE WRITE-FILE ; c-addr u fileid -- ior (== 0 | system err) FORTH-WORDLIST FILE Write u characters starting from c-addr to the file represented by fileid. Returns Windows NT LastError or 0 for success. This is a deferred word and is vectored at startup to the Unicode version WRITE-FILEW. See READ-FILE WRITE-FILEA ; c-addr u fileid -- ior (== 0 | system err) NONSTANDARD-WORDLIST ASCII version of WRITE-FILE. WRITE-FILEW ; c-addr u fileid -- ior (== 0 | system err) NONSTANDARD-WORDLIST Unicode version of WRITE-FILE. XOR ; x1 x2 -- x3 FORTH-WORDLIST CORE x3 is the bitwise exclusive-or of x1 x2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~ End of JAX4TH.DOC ~ ~ Jack Woehr ~ ~ Golden, Colorado ~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~