Click above to get retro games delivered to your door ever month!

  TRACK_HIT

  .  Summary

  track_hit(int <handle>);

  .  Description

  The track and related functions are used to keep track of and wait
  for certain strings to come in over the comm port, similar in nature
  to the waitfor function. However the latter function can only wait
  for one specific string, while with the track functions can handle
  more strings at the same time (currently up to 16), and they may ar-
  rive in any order (or not arrive at all).

  The track function tells Telix to keep track of (watch for) the
  string indicated by <trackstr> to come in over the comm port. If
  <mode> is 0, case is significant, if <mode> is 1, case is not sig-
  nificant. The former is faster and should be used when the many
  strings are being watched for. Track returns an integer value called
  a 'track handle' which is later used with the track_hit function to
  check if this string came in.

  When track is called, Telix doesn't loop endlessly waiting for the
  string to come in, but instead returns back to the script. As char-
  acters come in, Telix checks to see if any of the strings to be
  tracked have been matched, and marks those that have. A script can
  at any time call the track_hit function to see if the string repre-
  sented by <handle> was received. If track_hit returns a non-zero
  (TRUE) value, then that string was received, otherwise it wasn't. If
  <handle> is 0, then track_hit will return the lowest numbered handle
  of any strings that came in, or 0 if none did. The marker on a han-
  dle is cleared once track_hit has indicated that the appropriate
  string was received.

  While a script is executing, Telix is not in terminal mode, and
  therefore does not have access to incoming characters, to scan for
  matching strings. Therefore, the terminal function must periodically
  be called to allow Telix to get a look at incoming characters. This
  function is described in the appropriate place in this manual. Al-
  ternately, if a script must process these characters itself (with a
  function like cgetc), and therefore can not call the terminal func-
  tion, they must still be passed by the track routines for string
  matching to work. The track_addchr function is used for this. When
  it is called, Telix treats the character represented by <chr> as if
  it had been received from the terminal handler, and uses it to scan
  for matching strings.

  The track_free function is used to tell Telix to stop tracking a
  certain string. <handle> is a track handle returned by a previous
  call to the track function. It is very important that when a certain
  string no longer needs to be tracked, track_free is called, as
  tracking a large number of strings can slow down Telix execution. If
  <handle> is 0, Telix will stop tracking all string.

  .  Return Value

  Zero if a particular handle was passed and that tracked string has not
  been received.  Non-zero (TRUE) if a particular handle was passed and
  that tracked string has been received.  Zero if 0 was passed and no
  tracked strings have been received.  If 0 was passed and any tracked
  string has been received, returns the lowest number track handle of a
  string that has been received.

  .  Example

  // Log-on to a BBS, answering two prompts in any order.
  // This will wait forever, so for actual use would have
  // to be changed a bit. See sample scripts for examples.

  int stat, t1, t2;
  t1 = track("Name? ", 0);
  t2 = track("Password? ", 0);

  while (1)         // loop as long as needed
   {
    terminal();     // call terminal function to allow Telix
                    // to look at incoming characters for
                    // matches and let Telix process user
                    // keystrokes

    stat = track_hit(0);       // see if any matches

    if (stat == t1)            // name prompt
      cputs("Joe SmithM");    // send name and continue looping

    if (stat == t2)            // password prompt
     {
      cputs("mypassM");       // send password
      break;                   //   and get out of loop
     }
   }

  track_free(t1);              // free track handles
  track_free(t2);