Document Version: @(#)README.WZCLIENT	3.3.1.4

	wzclient - A remote runner for Wingz

wzclient is a tool to permit HyperScript commands to be sent from the
Unix command prompt to a running instance of Wingz 3.  The program
instance may be running either on the local machine or a remote machine.
The only requirement is that the program instance has loaded the wzlisten
boundin.

Loading the boundin:

To automatically load the boundin on startup, ensure that sure the boundin
wzlisten exists in $WINGZ3/plugins/$WZPLATFORM.  This can be done by
entering "make install" in this directory.

To manually load the boundin, ensure that the boundin wzlisten exists
in $WINGZ3/lib/$WZPLATFORM.  Then add the following command to Startup.scz
(or execute it in the running program):

GET BOUNDIN "wzlisten"

The program will then listen for connections from wzclient processes
and execute any commands passed to it.

NB: Only one program instance may listen on a specific port on one
machine at a time. If you wish to have several programs running, each
responding to a different command, then the environment variable
WZL_PORT may be set to an individual port number for each instance
(the default port number is "6666"). The specific port number may then
be specified when using wzclient (see below).

Using wzclient

Usage:
	wzclient [ -h host ] [ -p port ] [ -s password ] command | -f commfile

Example:

	wzclient 'NEW WORKBOOK "fred"'

This will connect to a locally running product, and run the command
'NEW WORKBOOK "fred"'.

The -h flag allows the command to be sent to a product running on a
remote machine. The -p flag specifies a different port for the
connection, to be used when several products are running on the same
machine with each listening on a separate port (specified using the
environment variable WZL_PORT). The -s flag specifies a password to
supply to the Wingz program (see Security below).

Commands may be placed in a file, and then sent in a batch using the -f
flag to wzclient. For example, if the file "batchfile" contains the
following lines:

NEW WORKBOOK ""
SELECT RANGE A1..C20
FILL
UNSELECT
ADD CHART RANGE A1..C20 USING A1..C20
PRINT NOW
QUIT NOW

Then the command:

	wzclient -f batchfile

will cause a new worksheet to be created, a graph to be drawn, the
sheet to be printed and the program to exit.

Security

wzlisten enforces a simple security model that checks the host, user
and group id, and method of connection. By default the only host that
is allowed to connect is "localhost" (i.e. the same machine), and the
user ID of the connection must match that of the person running Wingz.

The following functions in the wzlisten boundin allow this default
behavior to be modified:

	wzlisten:Hosts(name, mode)

Add (mode = 1) or delete (mode = 0) a host from the list of allowed
hosts. The return value is an n x 2 dimension string array, listing
currently allowed hosts by name and ip address.

	wzlisten:Mode(mode)

This function sets the authentication mode. Mode "USER" means the user
running WZClient must match the user running Wingz. Mode "GROUP" means
the group ids must match but the user id can be different. Mode
"OTHER" means any user from any group can run the command.

The function returns the previously set mode as a number, where 1 =
USER mode, 2 = GROUP mode and 3 = OTHER mode.

	wzlisten:Password(password)

This function sets a password that must be supplied by the wzclient
program (using the -s option described above) before a command may be
executed. By default, no password is required. The function returns
the previously set password. To clear a password call this function
with an empty string argument.

	wzlisten:DebugMode(mode)

This function is provided for trouble-shooting connection attempts. If
mode is set to 1, debug messages are printed to the console when
connection attempts are made. Setting mode to 0 turns off debugging.

WARNING: These programs can be used in malicious ways. The security
model is not designed to resist malicious attempt but to prevent
accidental control of Wingz. The user and administrator must take
other steps to ensure the security of the program environment in order
to prevent abuse of these facilities.
