Jax4th for Windows NT
Copyright 1993, 1994 Jack J. Woehr
PO Box 51, Golden, Colorado 80402-0051
jax@well.sf.ca.us 72203.1320@compuserve.com
SYSOP RCFB (303) 278-0364
All Rights Reserved
--------------------------------------------------------
This is free software and can be modified and redistributed under
certain conditions described in the file COPYING.TXT. The
Disclaimer of Warranty and License for this free software are also
contained in the file COPYING.TXT.

[Windows NT and MASM are trade names used by Microsoft for two of their
fine products and are the trademark property of that organization.]

This is Jax's free Forth for Windows NT. It's written in Microsoft MASM
6.11.

The source and documentation were prepared under Alan Phillips's
(alan@lancaster.ac.uk) PFE Programmer's File Editor 0.04.009. The font
was Lucida Sans Typewriter 7 which shows 124 characters by 31 lines in
a full-screen VGA window and was very convenient for the author. You
may have trouble browsing the source because of this, unless you are
using a large screen or an editor/browser which provides small fonts
for viewing and printing.

For Unicode files (such as UB2T.F in the UTILS subdirectory) you
can use the  Microsoft SDK's UNIPAD to view and edit, or you can
convert back and forth between Unicode and ASCII text with the
utilities UNIBLOCK.EXE and UNIASCII.EXE provided with Jax4th until
such a time as you find a decent Unicode text editor.

.BLK files are Forth BLOCK files and should be viewd in the Jax4th
system. These BLOCK files are 1024-character Unicode BLOCK files,
not good-old 1024 byte BLOCK files from the old days of Forth!
See JAX4TH.DOC for more info on BLOCK and file handling in
Jax4th.

The files are:
COPYING.TXT		LICENSE for this software.
READ_1ST.TXT		This file.
JAX4TH.EXE		Jax4th for Windows NT, executable.
UNIBLOCK.EXE		File conversion utility, ASCII > Unicode.
UNIASCII.EXE		File conversion utility, Unicode > ASCII.
JAX4TH.A		Jax4th for Windows NT, main source file.
JAX4TH.I		Jax4th for Windows NT, main include file.
JX4FILES.A		Jax4th for Windows NT, file-handling source.
WINDOWS.I		Jax4th for Windows NT, windows includes.
MAKEFILE		Jax4th for Windows NT, NMAKE makefile.
UNIBLOCK.C		UNIBLOCK.EXE source.
UNIASCII.C		UNIASCII.EXE source.
JAX4TH.ICO		Icon for JAX4TH.EXE.
JAX4TH.RC		Resource file for JAX4TH.EXE.
DOC\JAX4TH.DOC		Minimal documentation for Jax4th.
EXAMPLE\PASTE.BLK	Some utils and DDE example in Unicode BLOCK files.
EXAMPLE\SHORTEST.F	For testing PASTE.BLK.
OBJ4TH\DIMARRAY.UTF	N-dimensional self-indexing arrays.
OBJ4TH\MULTIOOP.UTF	Multiple-inheritance data objecs
OBJ4TH\OOPSOBJS.UTF	Sample objects for MULTIOOP.
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.

Release notes:
1.25 -- Fixed 2/ MIN / /MOD

	Added UTILS\DEFER.UTF and removed the old DEFER from UTILS.UTF.

	Added the subdirectory OBJ4TH with some interesting files
	implementing object extensions to Jax4th. See JAX4TH.DOC for
	more information on these files.

	Glossary is pretty complete now!

1.24 -- Fixed >

1.23 -- Changed the way UNFOUND and -13 THROW worked to make failed
	interpreter actions more CATCHable. Fixed SAVE-FORTH to make
	more sensible note of save operations aborted due to user
	cancel. Added YiQing.UTF to UTILS files.

1.22 --	Added EKEY? which is very similar to what I had in place for
	KEY? before. The new KEY? returns TRUE only for characters
	1Bh and above, with the addition of carriage return 0Dh.

1.21 -- Added EKEY and cleanup of struct declarations in WINDOWS.I ...
	There's more to do on this latter; remember, I start Jax4th
	under MASM386 which didn't allow nested structures. Almost
	got it all though.

	See the Glossary in JAX4TH.DOC about EKEY by the way.

1.20 --	Intermediate rev while working on EKEY.

1.19 -- Cleanup, had accidentally left some debugging in the previous rev.
	Anyway, you can now definitely SAVE-FORTH and RELOAD your saved
	image, but read JAX4TH.DOC carefully on these subjects first,
	particularly the sections "Invoking Jax4th" and "Saving a
	Dictionary".

1.18 -- Fixed WORDLIST and related words so that RELOADing would work
	correctly. Limitation: don't SAVE-FORTH with any except system
	wordlists in search order or current compliation vocabulary.
	I may fix this eventually.

	Cleaned up the definition of VOCABULARY in UTILS.UTF and cleaned
	up MEMORY.UTF.

1.17 -- Added GETCOMMANDLINE ( -- c-addr u). Fixed bug in COMPARE.

	Added SAVE-INPUT and RESTORE-INPUT (both CORE EXTENSIONS).

	Added SAVE-CON and RESTORE-CON which save and restore certain
	system items associated with the Console and its stacks for
	Jax4th.

	This is an intermediate revision in which RELOADing doesn't
	work entirely.

1.16 -- Added SAVE-FORTH. To save an image, first define the
	reload word, e.g., RELOAD-FID ..

		: RELOAD-FID ( file-id -- x x)
			0 CODETODATA 65536 ROT READ-FILE ;

	before loading any other code and then using SAVE-FORTH to
	save your image.That way, when you reload, the RELOAD-FID
	word won't get trashed while reloading!!!

		: RELOAD-FID 0 CODETODATA 65536 ROT READ-FILE ;
		ok0 MARKER FORGET-ME
		ok0 : TEST ." IT WORKS! " ;
		TEST
		IT WORKS! ok0
		SAVE-FORTH \ a filename requester comes up
		           \ let's say you choose "FOO.DIC"
		FORGET-ME
		ok0 TEST
		TEST? undefined
		ok0 S" FOO.DIC" R/O OPEN-FILE DROP DUP RELOAD-FID
		ok3 2DROP CLOSE-FILE DROP
		ok0 TEST
		IT WORKS! ok0

	This sounds strange, but I'll make it simpler in future
	revisions. At least now you can save and restore images!

1.15 -- Fixed OPEN-FILE analogously to the fix in CREATE-FILE in
	1.14 .. these are the only two Jax4th calls to CreateFileW.

	Broke up the JX4EXAMP.BLK file into Unicode text files and
	re-organized the distribution of the sample code. See
	JAX4TH.DOC for more information on the example code files
	(.UTF).

1.14 -- Added INCLUDED. Added BIN. Fixed CREATE-FILE so that it does
	string copying instead of using the string passed to it in
	place. This is because of the null which must end the string
	for the NT system call. S" was providing it, but WORD wasn't.

	Added the file UB2T.UTF, a Unicode source code example which
	shows how to convert Unicode BLOCK files to Unicode text
	files.

1.13 --	Jax4th now interprets text files! However, they have to be
	Unicode text files. UNIPAD.EXE 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.

	Added INCLUDE-FILE which interprets Unicode only!) Also added
	the variable FERROR in the NONSTANDARD-WORDLIST which saves the
	last file error for INCLUDE-FILE (and probably other file-related
	words in future revisions.

1.12 -- Added UDMIN and READ-LINE. READ-LINE is Unicode only!!.
	The Microsoft program UNIPAD.EXE is found in the %MSTOOLS%\BIN
	directory and it's Notepad for Unicode files. ALternatively,
	you can edit with an ASCII editor and use UNIBLOCK to convert
	from ASCII to UNICODE. UNIBLOCK comes with the Jax4th
	distribution.

	On the documentation front, I'm making progress but it still
	ain't finished.

	Next to add: INCLUDE-FILE INCLUDED ... Stay Tuned!!!

1.11 -- ***NOTE***  ***NOTE***  ***NOTE***  ***NOTE***  ***NOTE***
	Realized that READ-FILE WRITE-FILE FILE-POSITION REPOSITION-FILE
	etc. are supposed to deal with characters. They *were* written
	dealing with byte files which is the genuine file format of NT.
	SO ... 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 in COLD to READ-FILEW ..
	If you want to change the vector 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-POSITIONW instead of FILE-POSITIONA):

		FILE-POSITION
		FILE-SIZE
		READ-FILE
		REPOSITION-FILE
		RESIZE-FILE
		WRITE-FILE

	Incidental to all this, of course, is the fact that a DODEFER
execution engine has been added to the system.

1.10 --	DUMP and WORDS now pause on spacebar and resume on same, quick
	quit on any other keypress at either point.

	Discarded LocalLock() from the allocation of the data/userdict
	area, 	discarded LocalUnlock() from freeing of same, since
	allocating with LMEM_FIXED anyway.

	Added D>S 2>R 2R>

	Added a "Bye" message to BYE

1.9  -- Save EBX in SYSCALL just in case. Minor MASM 6.11 cleanups.

1.8  -- Assembly source now 6.11-style PROTOs, no need for CALLCONV.INC
	anymore. Added CHDIR to JX4EXAMP.BLK (useful!!).

1.7  -- Minor text changes ...

1.6  -- Added MARKER .... Added D0= ...

1.5  -- Changed numbering system, now it's just the RCS revision
	control number of jax4th.a

	Fixed headerlessness of WIDs, they used to make an UNNAMED
	header in the dictionary, now are truly headerless.

	Added UD.R U.R

1.06 -- Made sure CATCHing a -56 in the system catch does a QUIT

	More work on the glossary.

1.05 -- First general public distribution. Docs: Glossary still not
	finished.

BUG REPORTS AND SUGGESTED IMPROVEMENTS TO:
Jax (Jack J. Woehr)
PO Box 51
Golden, CO 80402-0051
jax@well.sf.ca.us
72203.1320@compuserve.com
SYSOP RCFB (303) 278-0364

<<END of READ_1ST.TXT>>

