DEMO

   1
   2                        Stem Demonstration Scripts
   3
   4 Stem comes with several demonstration scripts and example configuration
   5 files which are used by them. You can optionally install the executable
   6 demonstrations and their configuration files.  Note that the actual
   7 demonstration scripts don't do anything special to Stem, they just
   8 create windows and execute run_stem inside them with selected
   9 configuration files. They also create telnet connections inside other
  10 windows which you can use to interact with Stem. You can manually create
  11 the windows and do the same commands, these scripts are just
  12 conveniences. In fact, a good way to learn more about Stem is to copy
  13 and modify the configuration files used in the demonstrations and run
  14 them yourself.
  15
  16 When you run any of the demo scripts, the commands used to fork off an
  17 xterm are printed. You can manually run those commands in your own
  18 terminal windows if you want to experiment with or explore the Stem
  19 configurations. If you kill the script (e.g. with ^C), all the created
  20 xterm windows will be killed off leaving you with a cleaned up desktop.
  21
  22 There are 4 demonstration scripts that come with Stem. They are briefly
  23 described here and in more detail in other files. They all have some
  24 common features which are also described in detail below.
  25
  26         chat_demo and chat2_demo demonstrate a simple 4 user chat
  27         server. chat_demo runs with a single Stem Hub and chat2_demo
  28         uses 2 Hubs. Both bring up an xterm for each Stem Hub and 4 more
  29         for the telnet sessions. Read DEMO_CHAT for the full details on
  30         how to use this demo.
  31
  32         inetd_demo emulates the inetd Unix super-daemon. It runs a
  33         single Stem Hub in an xterm and 4 telnet sessions each in their
  34         own xterm. The server process it runs is proc_serv in the bin
  35         directory. You can run it directly from the command to see how
  36         it behaves (it is a simple command/response program).  Read
  37         DEMO_INETD for the full details on how to use this demo.
  38
  39         tail_demo monitors a typical log file and copies any new data it
  40         finds there to a Stem Logical Log which writes it to a file and
  41         optionally to other destinations. The status of the source file
  42         is also sent to a Logical Log.  Read DEMO_TAIL for the full
  43         details on how to use this demo.
  44
  45 Using the console Cell Stem::TtyMsg
  46
  47 All of the demo configurations include the Stem::TtyMsg module which
  48 allows you to enter command messages from the keyboard to a running Stem
  49 Hub (process). This module is not required to run Stem but it is in the
  50 demo configurations so you can interact with Stem and learn more about
  51 it.
  52
  53 It reads lines from STDIN (using the Stem::AsyncIO module so the rest of
  54 the Stem Hub continues to run), parses them and sends out a command
  55 messages based on the lines. It also can set key/values in the local
  56 Hub's environment (%Stem::Vars::Env) which is used to control many Stem
  57 operations.
  58
  59 Command messages can generate response messages which will be sent back
  60 to the TtyMsg Cell. These responses will be printed to STDOUT (again,
  61 using the Stem::AsyncIO module). Any Cell can just send a data message
  62 to the TtyMsg Cell (which is also registered with the class Cell name
  63 tty) and its data will get printed.
  64
  65 The rules for parsing lines input to TtyMsg are very simple. There are
  66 three kinds of command lines:
  67
  68         Direct commands
  69
  70                 The only direct command is 'help' which has to be the
  71                 only token on the line. It causes the help text to be
  72                 printed.
  73
  74         Setting a Stem environment variable
  75
  76                 Key/values in the local Hub's environment can be set
  77                 with lines of the form:
  78
  79                         name=value
  80
  81                 Token has to be only word characters ([a-zA-Z0-9_]) and
  82                 the string after the = is the value (stripped of
  83                 surrounding white space). The Hub environment variable
  84                 with the name token is set to the parsed value. The
  85                 token and value are printed.
  86
  87                 You can also set any environment variable in any remote
  88                 Hub with the command message:
  89
  90                         hub:var set_env name=value
  91
  92                 Note that 'hub' must be the real name of that Stem Hub,
  93                 and var is already the registered class name of the
  94                 Stem::Vars class Cell.
  95
  96                 See below for more on entering command messages and the
  97                 env_notes document in /Design.
  98
  99         Sending a Command Message
 100
 101                 A command message line starts with a Cell address and
 102                 then must have a command token. The rest of the line is
 103                 optional data for the command message.  A minimal Cell
 104                 address is just a Cell name. It can have an optional Hub
 105                 name prefix. Also a target name can be suffixed after a
 106                 trailing :. So the only legal Cell addresses look like
 107                 this:
 108
 109                         cell
 110                         hub:cell
 111                         :cell:target
 112                         hub:cell:target
 113
 114                 If the Hub is missing the message is destined for the
 115                 local Hub and if the Cell doesn't exist here, it is
 116                 routed to the DEFAULT Hub. Read the Cell and Message
 117                 technical note for more on this.
 118
 119                 The next token on a message command line is the command
 120                 name and it is required. It will be the value of the
 121                 'cmd' field in the message. The rest of the line is used
 122                 as the data field of the message.
 123
 124                 Some uses of command line messages are getting the
 125                 status of various Class Cells since almost all of them
 126                 have a status command. By listing all the registered
 127                 Cells you can see which ones you can send messages to.
 128
 129                 This will print all of the Cells in this hub. The
 130                 listing shows all object Cell and Class Cells with their
 131                 aliases. Command line messages should use the aliases
 132                 for the Cell name as the class names have colons in
 133                 them.
 134
 135                 This will print all of the Cells in the local hub.
 136
 137                         reg status
 138
 139                 This will print all of the Cells in the hub named remote.
 140
 141                         remote:reg status
 142
 143                 This will print all of the Portals in this hub. You can
 144                 use their hub names to send command messages to those
 145                 hubs.
 146
 147                         port status
 148
 149                 If you are running either chat demo you can change the
 150                 Switch maps which control which user get sent chat
 151                 messages. Here are some examples. The Switch Cell is
 152                 named sw, and the two Hubs in chat2_demo are named
 153                 chat_client and chat_server. Note that the 'sw' Cell is
 154                 only in the server Hub in chat2_demo, but since no 'sw'
 155                 Cell exists in the client Hub, any message sent to 'sw'
 156                 will still go to the server hub. So all of these map
 157                 commands can be issued from either Hub input and they
 158                 will work. The 'map' or 'status' token is the command
 159                 and the tokens after 'map' are data to the map
 160                 command. The first data token is the input map you are
 161                 setting and the rest of the tokens are the output maps
 162                 to send chat messages to.
 163
 164                 Print the current maps.
 165
 166                         sw status
 167
 168                 Change the a map to just b.
 169
 170                         sw map a b
 171
 172                 Change the d map to all users.
 173
 174                         sw map d a b c d