Script Cmd: CATCH

Options:

This turns on (or off) uCon's ability to "catch" an arbitrary string sent from the target and optionally run a script. The "catch" facility in uCon (new as of May 2008) allows uCon to run normally, but with an added bit of processing on the incoming characters from the target... If the target sends back to the uCon console one of the (up to 32) strings specified by "catch_stringN" above, then uCon will halt all active scripts asynchronously, and run the script specified by "catch_script" above. uCon will complete the catch_script prior to continuing with any futher stream processing (see note2 below)

Note that only one script can be specified, so, to allow the script to know which string caused it to run, the shell variable CATCHSTRING will be loaded with the string that caused the trigger; thus allowing the script to react to the string it caught with a simple set of "if" statements (see examples below).

New as of  June 2014:  
The "catch string" specified may contain dots and a special case "*\n" to deal with catching some initial string following by anything up to the next end-of-line.  This means you can specifiy an "any-character" position(s) within the catchstring; and when caught, the resulting value of the CATCHSTRING shell variable will contain the actual values caught.  This is in addition to the ability to handle any non-printable character using "\b, \r, \n & \xHH".

New as of  May 2015:  
The catch string can now simply trigger an end-of-line line tag (currently, this tag is the 4-character string: <<**.  This can accompany a script execution or it can be used in place of a script.   This just allows the user to have uCon place a line tag at the far-right edge of the console window on the same line that that triggered the catch.  This just allows a user to more easily notice a trigger.  Line tagging mode is established with the new "tagon | tagoff" arguments, or it can be specified by the "Line Tagging" checkbox within the dialog (see below).  Check out Example 5 below.

NOTE1:
The state of the catch facility (script/strings) is shown through the Config->Environment->Display dialog. If catch is disabled nothing is dumped; if enabled, it will display the script and strings.

NOTE2:
If the -n option is specified, then no catch script is specified; hence, no script is executed if a catch string is caught.  Instead,  the CATCHSTRING is populated and the equivalent of "CATCH off" is automatically executed.

NOTE3:
Normally (with -a not specified), uCon runs the catch-script in a blocking mode; meaning that it holds off on processing any additional input from the comport until the catch-script completes.  There are many cases where this is not ideal; hence if the -a option is specified, the script will be started at the same trigger point; however, the comport thread will not be blocked while the catch-script runs.  Also note that when -a is used, when a catch-script is triggered future triggers are immediately disabled (until the next CATCH script command is invoked).  This is because of the fact that the catch-script is now running while additional comport activity is being received and there would otherwise be potential for a subsequent catch-trigger to override (kill) the running catch-script.  

NOTE4:
The CATCHSTRING shell variable is likely to contain whitespace, so be aware of the need to put the shell variable within double quotes as needed to make sure that the string is parsed as a single token.

NOTE5:
Basic 'catch' setup can also be done with the Scripts->Catch dialog box.

This dialog provides a subset of what the CATCH script command provides.  It only allows the user to specify one "catch string".  For convenience, the "Clear" button can be used to quickly disable any prior CATCH setup (similar to "CATCH off" script command).

NOTE6:
When using the "*\n" capability in CATCH, its possible that the caught text will include characters that (when pushed into the CATCHSTRING shell variable) will cause confusion on the command line.  The '-f' (fixup) option will automatically insert a '\' in front of a double qoute or a backslash so that the script command line will properly parse the CATCHSTRING shell variable. 

NOTE7:
This "catch" facility runs essentially in the "background". All other normal uCon facilities are availalble to the user. The only thing to be aware of is if a script is active when the incoming "catch_string" is detected, that script will be asyncrhonously halted to allow the "catch_script" to run (assuming -n was not specified).  As of June 2014, the -h (don't halt) option allows the user to "carefully" run the catch script while other scripts are left active.  Typically, the other script will be waiting on a dialog box or doing something rather limited in scope.  This option is made available with the understanding that there are cases where running two scripts in parallel will cause one to step on the other; so use it at your own risk!

EXAMPLE1:

Run the setup script to initialize the catch mechanism to look for strings "panic" and "alert", so that in either case the script called "catch_script" is executed as a result of the catch. When "catch_script" runs, it looks at the content of the CATCHSTRING shell variable to determine where to branch.

EXAMPLE2:
Use just 1 script, for setup and catch...
Assume the file "catch_script" as follows.

In this case, we have to assume that if CATCHSTRING is not populated, then the script is being called for setup.  At startup, this is certanily the case; however, if unsure, just click on the 'Clear' button in the dialog box shown above. To keep the state of CATCHSTRING organized, we clear the CATCHSTRING shell variable whenever the script is responding to a trigger.

EXAMPLE3:

EXAMPLE4:

EXAMPLE5: