* * * SONZEN (Son of) Zen Forth * * *
* * * DOS version of C986 Zen FORTH * * *

Run with -h flag for command line options help
Run with -i flag for more info (-I pauses after each screen)
FORTH word MTERM is a terminal emulator.
================================================================
|||||| SONZEN - "Son of Zen" FORTH ||||||||
================================================================
7/27/88 Chuck Grandgent
AEG Modicon, Industrial Automation Systems Group
(ex-Gould Electronics, IASG)
50 Westvale Drive

Concord MA 01742

Usenet : sun!portal!cup.portal.com!chuck_m_grandgent
Compuserve : 72330,450
GENIE : C.Grandgent
AEG Co-Pro BBS 508-975-9779 (PCBoard)
(obviously a BBS junkie...)

This FORTH is a derivative of Martin Tracy's Zen Forth.

I am posting this particular edition only because I think it
is an interesting example of a hybrid <>
combination best used as a "Swiss Army Knife" for debugging
a (unique) environment.

But first, a message from our sponsor.........

Martin puts out a nice Zen Forth package for the IBM PC which
comes with a nice manual and all the source (except the
metacompiler). It includes things like multitasking, full screen
editor, assembler vocabulary, etc. Zen Forth is an ideal
system for learning Forth, because it is simple and elegant and
unencumbered bye the TONS of stuff typically accompanying most
Forths. It goes along with the text "Mastering Forth, 2nd
Edition", by Anderson and Tracy.

For more information on Zen Forth, contact the author:
Martin J. Tracy
2819 Pinckard Ave.
Redondo Beach, CA 90278
(213) 371-0589

In addition, THIS implementation may not be sold or used for profit
and absolutely no warantees are made with respect to ANYTHING about
this software - it is meant for educational use only.

Now, on with the show................

About this FORTH:
This Forth is an assembler language (as opposed to metacompiler)
based FORTH derived from Zen Forth. It uses a method for linking
in Microsoft "C" routines (large model).
It was developed as a debugging tool for an industrial coprocessor
board (Intel chip based) running the Ready Systems' VRTX
multi-tasking O/S. This board originally could only be programmed
by downloading Intel HEX files on the RS-232 port, hence the
development cycle was very long and drawn out - edit, compile,
link, build system image, download on RS-232 port, test program,
edit...., etc. Forth was desired because it was small and
interactive and hence could be a good resident "O/S" and environment
for testing during development of the board.

Since a lot of what needed to be tested was "C" routines
(that being the dominant language for the board), I developed
a method of linking in the "C" routines to the Forth words.
I believe the technique is described in a file available on the
ECFB called FORTH2C.ARC (or somesuch name).

The assembler code was set up to conditionally assemble for
either the VRTX or MSDOS environment, to make testing and
developing the FORTH easier. This SONZEN is for DOS environment,
and has some interesting words built in for RS-232 communications.

Upon starting SONZEN, if no command line arguments are provided,
it installs interrupt handlers and programs the UARTs for
9600 baud, 8 bit, No parity. It has an interrupt-driven 2k
ring buffer, and can fully keep up with 9600 baud, even on a
4.7Mhz-based 8088 system (no big trick). To fire it up with
different settings, run SONZEN with the -h flag.

While many of the words in SONZEN's vocabulary are only
appropriate to the VRTX environment on our "Co-Pro" board,
there are some good ones for handling RS-232 communications.
They are DGETS, DGETSBIN, DPUTS, DPUTSBIN, and they are described
below. The documentation for these words is from the "C" library
routine documentation.

Many of the words which link to "C" will display their stack
definition if they are invoked with nothing on the stack. For
example, type in DGETS with nothing on the stack, to see the
stack definition. Most of the words not appropriate to the MSDOS
environment have protection built in so they do nothing under DOS,
but I don't guarantee you won't find one that may hang your machine.

Miscellaneous:

WORDS will display the vocabulary.

MTERM is a tiny terminal emulator, after invoking it, press F1
for help.

To open a "screen file", type in FOPEN. You will be prompted
for the file name and will be informed of successful or unsuccessful
opening of the file. It is OK to LOAD block 0 with this FORTH.
FOPEN closes a previously opened file before prompting for a file
name. FCLOSE can also be issued. SONZEN attempts to open DZEN.TXT
when it is first started.

The MODDEMO word issues the Modbus industrial protocol request
to read holding registers from a Programmable Controller. It
starts off in "ASCII Modbus". By starting in MODDEMO and pressing
a key to stop it, and then typing in 1 MODMODE !
it will switch to "RTU Modbus", and may be restarted by typing
in MODTEST.

Words READREGS, WRITEREGS, DBREAD, DBWRITE, READABS, WRITEABS,
IOOPEN, IOWRITE, IOREAD, IOCLOSE, etc., do things specific to
the VRTX Co-Pro environment. For example, READREGS reads memory
from the Programmable Controller across the backplane.

Words CMDBUFF, REPBUFF, TBUFF are all 524 byte general purpose buffers.

One interesting thing was that all DOS disk handling words
are funneled through the word FDOS. For the VRTX environment,
this was not changed. Instead, FDOS calls a "C" routine which
has a large "switch" statement, with "cases" for each Dos subfunction
code. It then issues the appropriate VRTX environments to carry
out that function. In this way, the bulk of the Forth supports
either DOS or VRTX with all the mapping done in one module.

The beauty of the assembler-"C" combination was that by using
this method, we were testing the exact same "C" routines we used
elsewhere, but from a stack-based, interactive environment.

As a Forth-based application development environment, this
Forth just doesn't make it, since it is broken in many places and
missing many things normal Forthers expect. For example, if you
start a definition with : then type some stuff and a carriage
return, then continue the definition on another line, and finally
terminate the definition with a ; - it will hang, requiring
(probably) reboot. I haven't fixed this yet. Once you enter
a colon, you should keep entering the definition until the terminating
semicolon WITHOUT using the carriage return.

I would be happy to answer any questions anyone might have,
or elaborate on specific areas of the implementation or what we
do with it. And, you are welcome to drop by the AEG Modicon
Co-Pro BBS (where I am Sysop) at 508-975-9779, or voice at
508-975-9622.

================================================================

dgets() Input a string of chars
dgets_bin() Input a string of chars (binary data)
dputs() Output a string of chars
dputs_bin() Output a string of chars (binary data)
______________________________________________________________

DGETS Input a string of chars
______________________________________________________________

Prototype

int dgets (int comm_port, char *buffer,
int buffer_length, int timeout);

(timeout is in units of 20 msec.)

Usage:

char ch;
char buf[1]; /* wait for single character */
if (dgets (1, buf, 1, 0) < 0) error();
else ch = *buf;

Exit Codes

+n Successful return (number of chars read)
-1 Error occurred

Function

Inputs a string of characters from COM ports 1, 2, 3, or 4
until the specified number of characters has been received or a
delimiter (CR or LF) is encountered, whichever occurs first. The
characters are stored in the caller's buffer, and the function returns
the number of characters received regardless of whether a timeout
occurred. If the number of characters received is less than the
requested length, the buffer is terminated with a NULL ("
character for convenience. It is also possible to receive no
characters (0) from this call.

When it is important to know whether a timeout occurred, this
case may be determined by checking for an empty buffer or a delimiter
in the buffer:

if ((n = dgets (commport, buf, buflen, timeout)) < 0) error();
if (n ==0 || (buf[n-1] != "\r" && buf[n-1] != "\n"))
timeout_occurred;

Note that a null character ("
another device and stored in the buffer. In such a case, if you use
strlen() (Microsoft C library function) to determine the length of the
buffer as in the example

while (1) {
dgets (2, buf, 80, 0);
dputs (3, buf, strlen(buf));
}

then the device at port 3 may not receive every character transmitted
by the device at port 2. The value returned by the dgets() function
is the TRUE number of characters received.

______________________________________________________________

DGETS_BIN Input a string of chars
______________________________________________________________


Prototype

int dgets_bin (int comm_port, char *buffer,
int buffer_length, int timeout);

Usage

char ch;
char buf[1]; /* wait for single character */
if (dgets_bin (1, buf, 1, 0) < 0) error();
else ch = *buf;


Exit Codes

+n Successful return (number of chars read)
-1 Error occurred


Function

This function is identical to dgets(), with the exception that
no delimiters are recognized. It terminates only when the specified
number of characters has been read or a timeout occurs. This function
is intended for binary data reception.

______________________________________________________________

DPUTS Output a string of chars
______________________________________________________________



Prototype

int dputs (int comm_port, char *buffer,
int buffer_length);


Usage

dputs (1, "hello, world", 80);

int i;
char buf [80];
i = sprintf (buf, "%s", "hello, world\r\n")
dputs (port, buf, i);


Exit Codes

0 Successful return
-1 Error occurred


Function

Outputs a string of characters with specified length to COM
ports 1, 2, 3, or 4. The data is written to the port from the
caller's data buffer until the specified number of characters has
been transferred or a NULL (
The statement

dputs (port, buffer, 81);

can be used as a generic print statement when the buffer is always
terminated by "
terminated by a NULL, then all 81 characters may be sent, and you
should use the exact length instead.

______________________________________________________________

DPUTS_BIN Output a string of chars
______________________________________________________________


Prototype

int dputs_bin (int comm_port, char *buffer,
int buffer_length);


Usage

dputs_bin (1, "hello, world", 80);

int i;
char buf [80];
i = sprintf (buf, "%s", "hello, world\r\n")
dputs_bin (port, buf, i);


Exit Codes

0 Successful return
-1 Error occurred


Function

This function is identical to dputs(), with the exception that
no delimiters are recognized. It terminates only when the specified
number of characters has been printed. This function is intended for
binary data transmission.

----------------------- End of File ---------------------------------