
This directory contains example main occam processes.  kroc provides
a simple interface to UNIX stdin, stdout and stderr file descriptors.
The main kroc process must have the form:

  PROC foo (CHAN OF BYTE stdin, stdout, stderr)

Inside the body of foo, inputs from stdin take single characters
from `UNIX stdin'.  Outputs to stdout or stderr send single
characters to `UNIX stdout' or `UNIX stderr' respectively.

kroc runs stdin in `raw' mode without echoing - i.e. individual
keystrokes are supplied to the occam process immediately (and not
buffered up until a carraige-return is typed).  If we need echoing
of keyboard input, the occam process will have to be programmed to
do that by outputting down stdout.  However, kroc runs stdout and
stderr in line-buffered mode - i.e. characters are not normally
delivered to the screen until a carriage-return is output.  To
overcome this, kroc forces buffered characters to be flushed if
the BYTE value 255 is output to stdout (or, respectively, stderr).
An example of this is given in the echoing.occ file.

Note that the identifier names foo, stdin, stdout, stderr in the
above main PROC declaration are user-defined.  Just as good is:

  PROC my.thing (CHAN OF BYTE keyboard, screen, error)

However, all three parameters have to be present even if they are
not all used.  The first one is mapped to `UNIX stdin', the second
to `UNIX stdout' and the third to `UNIX stderr'.

The example processes are in the files:

  hello_raw_world.occ

    This just outputs the expected message to stdout.  It uses no
    libraries and some very primitive occam.
  
  hello_seq_world.occ

    This also outputs the expected message.  However, it declares
    the message as a string constant and uses a simple SEQ-loop
    (which corresponds to a for-loop in Modula-3) to output the
    characters in sequence.  It also uses no libraries.
  
  hello_world.occ

    This uses a library procedure to output the string.

  echoing.occ

    This is a simple process to echo characters from stdin to stdout.
    To make it slightly interesting, each character is echoed twice.
    Note the use of the FLUSH character (which is defined in the
    #INCLUDEd file consts.inc - see the /usr/work/kroc/libsrc directory).
    The process terminates after echoing the character 'Z'.

  test_utils.occ

    This is a process that shows how to use all the procedures and
    functions provided by the utils.occ library (whose source code
    and documentation are in the /usr/work/kroc/libsrc directory).

  demo.occ

    This process will be explained in the course.  It demonstrates
    the `legoland' components defined in the demo_cycles.occ and
    demo_nets libraries (sources in /usr/work/kroc/libsrc).

  sort_pump.occ

    This process will be explained in the course.  It demonstrates
    the functionality of a parallel `sort pump', viewed as a black box.
  
  sort_inside.occ

    This process will be explained in the course.  It demonstrates
    the internal workings of the parallel sort pump.

Take your own copies of all these processes.  Once in your directory
space, you may compile any of these files by applying kroc - e.g.

  % kroc sort_inside.occ

which produces an executable called sort_inside.  Run this - i.e.

  % sort_inside

and you are in business!

Peter Welch.
