		     SCADALisp, Shareware Release
		    Cogent Real-Time Systems Inc.
			  September 20, 1995

Table of Contents
=================

1.  Changes Since the Last Release
2.  Hanoi
3.  Imageview
4.  Puzzle
5.  Mines
6.  Cpumon


1.  Changes Since the Last Release
==================================

Version 1.7.3
=============
a.  Added the cpumon example program and associated QNX system
    functions. 
b.  All examples now have usage messages for the QNX 'use' command.


2.  Hanoi
=========

The Towers of Hanoi puzzle is commonly used to demonstrate recursion
capability in languages which implement lists as a data type (you
don't see too many C implementations of the Towers of Hanoi because
the book-keeping is too much of a nuisance).  The object is simple:
you have a stack of discs in descending order of diameter on a peg.
You have 2 other pegs with no discs on them.  You must move the entire
stack of discs to another peg, following these rules:
   1) You can only move one disc at a time, from one peg to another,
   2) You can only move the top disc on any peg,
   3) You can never place a disc on top of another which is smaller in
      diameter.

The solution takes 2^N-1 moves, where N is the number of discs.  It
can be easily solved recursively.  To move any stack of discs to
another peg, move all but the bottom one to an intermediate peg, then
move the bottom one to the destination and move the intermediate stack
back on top of the bottom disc.  To move a sub-stack, move all but the
bottom one to an intermediate peg....

The Towers of Hanoi demonstration has a Photon and QNX Windows
interface, all in a single source file.  It will automatically detect
which window system you are running and display the solution as it is
being solved.  This is a very good example of how to do user interface
in the two window systems.  The automatic detection is based on which
executable you are running, so a shell script has been provided to
look for the /dev/photon special file to determine if Photon is
running and to start the appropriate executable.

To run:

	hanoi			- either Photon or QNX Windows
	phlisp hanoi.lsp	- Photon
	qwlisp hanoi.lsp	- QNX Windows


3.  Imageview
=============

This is a simple image viewer for Photon which allows simultaneous
display of multiple images.  It demonstrates how to manipulate images
in SCADALisp and how to create custom modal and non-modal dialog
boxes.  The file selection dialog was constructed in the Photon
Application Builder and animated in SCADALisp.  The source and .wgtw
files are in the lib directory.

Imageview has the following parameters:

	-b		- do not draw borders on the image windows
	-g width height	- create thumbnails not exceeding width in the
			  x dimension and height in the y dimension,
			  while maintaining the aspect ratio.
	-r reduction	- reduce the image by a fraction (e.g., .5 = half)
	-w		- load .wgtw files instead of image files.
	filename...	- display each file named on the command line

To run:

	imageview
	phlisp imageview


4.  Puzzle
==========

This is the 4x4 puzzle game.  Unscramble an image by moving parts of
it into the empty spot.  You provide the image to use on the command
line, or if none is provided, you choose from a file selector.  This
demonstrates image partitioning and movement.  Note the use of the
Pt_BLIT_FORCE flag when setting the position of the image.  Only
PhPoint type resources can use this syntax to deliver an extra flag to
the resource.

Puzzle has the following parameters:

	-r reduction	- reduce the image by a fraction (e.g., .5 = half)
	filename	- use the file named on the command line

To run:

	puzzle
	phlisp puzzle	


5.  Mines
=========

This is the mine sweeper game for Photon, pretty much like the one in
MS-Windows.

Commands:

	left button on block	- expose a block.  If it is a mine,
				  you lose.
	left button on number	- expose all adjacent blocks if the
				  correct number of mines is marked
				  adjacent to this number
	right button on block	- mark this block as a mine, or if it
				  is already marked, unmark it.

This program demonstrates the use of timers and active value functions
to keep track of the number of seconds in the top right corner.  The
flashing colors when you win are also implemented using a timer.

The mines program has been implemented in both SCADALisp and SLANG to
provide a basis for comparison between the two.  The SLANG
implementation includes a high-score list, demonstrating some simple
file system functions.

Mines has the following parameters:

	[rows [cols [mines]]]

	Specifies the number of rows, columns and number of mines.
	The default is 10 10 20.  A good game is 15 25 100.

To run:

	mines			- SCADALisp mines
	phlisp mines
	phslang smines		- SLANG mines

6.  Cpumon
==========

This is a simple CPU monitor which will display the combined CPU usage
for all tasks, or the CPU usage for a particular priority, along with
the available system memory, as continuous trends.  The program
consists of two parts:
    cpumon	- a front end for the CPU and memory monitor, providing
		  usage and command line argument parsing.
    cpumem.lsp	- a small program which may be read in as part of a
		  larger program whose behaviour can be modified
		  through a set of global variables.

This program demonstrates one method of re-using code:  a stand-alone
program which will run from within another program without
interference.  This can be useful if you have several small tasks
which you wish to run in a single SCADALisp executable.  The use of
timers and events as triggers provides a sort of poor-man's multi-threading.

Parameters:

cpumon [-i integration] [-u update] [-1|-2] [-c color1 color2]
    -i    Set the integration rate in seconds, default 3
    -l    Set the CPU level to watch, 0 for all combined, default 0
    -u    Set the update rate in seconds, default 0.1
    -1    Display both traces on a single graph, default on
    -2    Display each trace on its own graph, default off
    -c    Set the colors for the two traces, default 0xff 0xffff
