Input functions
---------------

Input functions take a single argument:  mode (an integer).
Mode takes one of three values:

   * TOP_STATE_JUST_CREATED: indicates that the top state has just been
     installed.  Normally this only happens on the very first I/O cycle, but
     it could also happen if the top state were reconsidered and replaced.
     Your function should do whatever initial steps are necessary---for
     example, creating the initial input links and structures in WM.
     
   * TOP_STATE_JUST_REMOVED: indicates that the top state has just been
     removed.  Normally this only happens when the user does an (init-soar).
     Typically, you just want to do some cleanup here, like releasing
     leftover I/O symbols.
     
   * NORMAL_INPUT_CYCLE: indicates a standard input cycle.  Do the real I/O
     stuff in this case.
     
 

Thus, a typical input function looks like this:

Symbol *top_input_link_id;

void my_input_function (int mode) {
  switch (mode) {
  case TOP_STATE_JUST_CREATED:
    /* Initialize & internalize objects. */
    top_input_link_id = get_new_io_identifier ('I');
    ...
    break;
  case TOP_STATE_JUST_REMOVED:
    /* Clean up. */
    release_io_symbol (top_input_link_id);
    ...
    break;
  case NORMAL_INPUT_CYCLE:
    /* Standard mode of operation. */
    ...
    break;
  }
}