
                            IPC Demo Sources
                            ================

This directory contains source files for a Simple Server/Client pair
-- the client simply sends text to the server for output -- and a more
complex Print Formatting Server ("FormatServer"), with a very dumb Client
program to test it ("FormatClient").  There are also a simple Port Broker
and a "Cleaner" for checking and fixing errant IPCPorts, plus very short
program that will send a standard QUIT message (which should be recognized
by ALL servers) to specified IPCPorts. These sources are mostly heavily
commented, and are intended as demonstrations of how to use the IPC
protocols.  The icons at the parent level of this package will actually run
these demo programs if you want to try them out.

Include header files:

    IPC.h   -- a copy of the file from IPC_Sources, for convenience.
    IPC_proto.h -- direct library call definitions for Lattice 4.0/5.0


Source Files:

    SimpleServer.c
    SimpleClient.c

    Quit.c

    FormatServer.c
    FormatClient.c

        Both of the "Format.." modules must be linked with the
        floating-point math library.

    Broker_skel.c   -- an incomplete core structure for a Port Broker
    Broker.c        -- a simple working Broker
    Cleaner.c


Documentation:

    FormatServer.doc --  A detailed description of the message format
                    accepted by FormatServer, and the requirements for
                    using it.

    FormatClient.doc   --  A short description of the test program and its
                        commands.


    For more on the Broker and Cleaner programs, please refer to the Broker
    directory.

                            ++++++++++++++

Compatibility:

    These programs have been tested under Lattice 5.02/5.04.  They will
    need some conversion (ensuring LONGS are used where necessary, and so
    on) for compilation under Manx (and will also need assembly library
    linkage routines).


Notes:

    The two "Simple..." programs are trivial examples of accessing an
    IPCPort and passing simple messages.  They should be straightforward
    to follow.  The "Format.." examples are much more extensive; the server
    in particular has to do a lot of work to handle all the items that
    might be thrown at it; it is probably mure complex than a good example
    program should be...  The FormatClient, too, plays a few games with
    messages, just to test out the system.  If they are intimidatingly
    complex, my apologies.

    The Format handling programs have been written to reduce space as much
    as possible: they use '_main()' rather than main(), for instance, and
    don't use C level I/O -- just AmigaDOS calls.  They should be compiled
    using the Lattice -v switch, to reduce space a little more, and there
    may be other measures that could be taken.

    This means that they CANNOT be invoked directly from an icon in their
    present form -- only from a CLI.  AS they need to run simultaneously
    they must either be started from their own CLI, or with the RUN command
    (remembering that they both can generate console output).

    You can use an Xicon script to set them both going in a suitable
    environment (as in the demo icon in this package), but there are TRAPS!
    These seem to be due to a bug in (1.2 -- may be fixed in 1.3) RUN,
    which has problems when it is invoked from an AmigaDOS Execute() call:
    you MUST redirect the output of RUN ITSELF to NIL: to avoid Guruing.
    For example:

        RUN >NIL: FormatServer >"CON:100/50/450/100/Format Server Output"

    [This is nothing to do with IPC -- it is a general problem Xicon has
    with AmigaDOS -- as far as I can tell, it's the systems fault (:-))]
    See the script for the demo (in directory IPC_demo) for more details.


