What it is:
  XCenter Rexx Gauge Widget script to show completion percentage
  of the current Seti@Home ("s@h") work unit.

Note:
  This is the "newer" version that fixes an ERROR-41 bug that occured
  when the work unit was finished and no new one was being worked on yet.
  (No state.sah file -> no progress= line -> error on string formatting)

Requires:
  - The popular "rexx gauge" widget included in Martin Lafaix' 
    XWorkplace Widget Library on http://lafaix.online.fr/wpi
  - XCenter to be set up functional and running
  - Seti@Home client for OS/2 (tested with v. 3.3)
  - *NO* additional seti wrapper, pipe process or DLL.

What it does:
  - Shows % of current work unit numerically (e.g. "76,31%")
  - Shows % using gauge display (bar graph), color=GREEN
  - Shows "-?-" if state file / progress not found (e.g. work unit finished,
    no new available yet)
  - Gauge color turns from green to red if no change of percentage was
    noticed for a given time (default: 1 min)

How to setup:
  - click MB2 (context menu) on xcenter, select "add widget", then "rexx gauge"
    This will setup an empty widget space.
  - Again, use MB2 on the widget, select "properties".
  - Select a title (will be displayed in tooltip) by entering e.g. "S@H state"
    in the entry field named "Default Title"
  - Copy/Paste the content of setiprog.wgt into the entry field "gauge script".
 That's it. Basically. 
  - You will need to modify the rexx line beginning with "sahfile=" to reflect
    the full qualified filename (drive letter, path, filename, extension) of
    YOUR seti@home status file. Usually, it's called "state.sah" and resides
    in the seti client's program directory, if a current work unit is present.
  - To go with my defaults, use a refresh rate of 10000 ms (10 seconds).
  - The gauge width depends upon your preferences/settings. I'm using it with
    a fixed width of 45 pixels.
  - Click "OK" and there you go... (hopefully.) ;)

Fine-tune:
  If you notice the gauge bar is turning red although the s@h client is still
  working, it'll simply mean that the s@h percentage did not change for more
  than a minute. This might happen in case your s@h client was set up to
  consume less cpu or it wasn't granted enough performance (either from the
  scheduler or from your hardware <g>). In this case, you might want to
  increase the amount of time that the script will wait for a change in
  progress before "turning red"...:
  This is calculated upon the gauge's Refresh rate and the value of the
  "MaxChecks" variable - when using a refresh rate of 10000 ms, the script
  will check the percentage each 10 seconds. If MaxChecks equals to 6, it'll
  mean 6 * 10 seconds before turning red (=1 minute).
  So simply calculate the desired "MaxChecks" value from the refresh rate you
  specified for the script. Obviously, you can get the same behaviour by 
  specifying a refresh rate of 60000ms with a MaxChecks of 1. This will make
  the script run only once per minute instead of every 10 seconds, actually
  with the same result. BTW: I chose MaxChecks=7 to make sure that there's
  more than one minute elapsed before the gauge starts complaining...
  I'm sorry to bother you that way, but I'm no such good rexx programmer and
  I didn't know what to do else... ;)

One more fine-tuning hint:
  As we folks from Germany actually use a COMMA to show decimals, you'll
  notice the display does show "12,34%" instead of "12.34%"...
  If you want the decimal-point back, simply remark or remove the line

    dprog = translate(trunc(prog * 100, 2), ",", ".") || "%"

  near the end of the script and use the second one instead:

    dprog = trunc(prog * 100, 2) || "%"
  (You'll have to remove leading and trailing comments "/*" and "*/")

  Of course, I could have checked the country settings, but hey - that would
  mean one more "IF" instruction every ... milliseconds! ;)

How it works:
  As long as your s@h client has an unfinished work unit, there's a
  "state.sah" file present as well (even if the client is not running).
  This file does contain a line starting with "prog=" that holds the
  "current" progress of the work unit completion.
  The script simply reads the value, decides if there was a change and does
  some litlle work for better readability. That's all. Nothing magic.
 
About this script:
  Actually, I intended to look up the window list to see whether the s@h
  client is still present. But I didn't find out how to do it without the
  need of additional DLL's or complicated stuff.
  Remember: The whole script is processed every [refresh rate] milliseconds.
  Whew. So instead, I decided to use the pid.sah file content along with
  "PSTAT /P:nnn" queued to RXQUEUE to check whether the s@h client is still
  alive (present) or not. Unfortunately, I can't use the PULL command (to
  retrieve the queued outputs) from within the rexx gauges... so I had to
  work around this limit and came up with the idea of checking, whether the
  percentage did not change for a given amount of time by using the gauge.user
  variable... sorry. ;)

Possible enhancements:
  If someone knows how to make the s@h's VIO session re-popup to foreground
  by using rexx, that would make sense as a "double-click action" script.
  Or maybe using "userinfo.sah" to get your s@h e-mail adress and browse your
  individual stats page...?

Suggestions:
  I'm only starting with rexx, so if there's something that you might want to
  improve... go on and email me your corrected/improved version of the file.
  Especially, if you're able to speed up/simplify the task, don't hesitate 
  to let your community benefit from your brainwork and tell us!

Legal stuff:
  Freeware. Use at your own risk. No warranties.
  You're allowed to do whatever you want with this script, like changing it
  and uploading it somewhere else as long as you're doing it the same way
  I did: No copyrights!

Have fun.
Th.Klein

email: warpcafe _at_ yahoo.de
