/usr/share/doc/blt-dev/html/bgexec.html

                     <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->

<HTML>
<HEAD>
<TITLE>bgexec(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>
 
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
bgexec - Run programs in the background while
handling Tk events. 
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>blt::bgexec <I>varName</I></B> ?<I>option value</I>?... <I>program</I> ?<I>arg</I>?...

<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
<P>
The <B>bgexec</B> command executes programs in the background, allowing
Tk to handle events.  A global Tcl variable <I>varName</I> is set when the program
has completed. 
<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
Tcl's <B>exec</B> command is very useful for gathering
information from the operating system.  It runs a program and returns the
output as its  result.  This works well for Tcl-only applications. But for
Tk applications, a problem occurs when the program takes time to process.
 Let's say we want the get the disk usage of a directory.  We'll use the Unix
program <I>du</I> to get the summary. <BR>
<CODE>set out [exec du -s $dir]<BR>
puts "Disk usage for $dir is $out"<BR>
</CODE><P>While <I>du</I> is running, scrollbars won't respond.  None of the Tk widgets will
be redrawn properly.  The <B>send</B> command won't work. And the worst part is that
the application appears hung up or dead. The problem is that while <B>exec</B>
is waiting for <I>du</I> to finish, Tk is not able to handle X events. <P>
The <B>bgexec</B>
command performs the same functions as <B>exec</B>, but also allows Tk to handle
events.  You can execute a long-running program and the Tk widgets will behave
normally.  When the program finishes, its output and the exit status are
written to Tcl variables.  This makes it easy to monitor and save the output
of a program. 
<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
Here is the disk usage example again, this time using
<B>bgexec</B>. The syntax to invoke "du" is exactly the same as the previous example,
when we used <B>exec</B>. <BR>
<CODE>global myStatus myOutput<BR>
blt::bgexec myStatus -output myOutput du -s $dir<BR>
puts "Disk usage for $dir is $myOutput"<BR>
</CODE><P>Two global variables, <I>myStatus</I> and <I>myOutput</I>, will be set by <B>bgexec</B> when
<I>du</I> has completed. <I>MyStatus</I> will contain the program's exit status.  <I>MyOutput</I>,
specified by the <B>-output</B> option, will store the output of the program. <P>
You
can also terminate the program by setting the variable <I>myStatus</I>.  If <I>myStatus</I>
is set before <I>du</I> has completed, the process is killed. Under Unix, this
is done sending by a configurable signal (by default it's SIGKILL). Under
Win32, this is done by calling <B>TerminateProcess</B>. It makes no difference
what <I>myStatus</I> is set to. <BR>
<CODE>set myStatus {}<BR>
</CODE><P>There are several <B>bgexec</B> options to collect different types of information.
<BR>
<CODE>global myStatus myOutput myErrs<BR>
blt::bgexec myStatus -output myOutput -error myErrs du -s $dir<BR>
</CODE><P>The <B>-error</B> option is similar to <B>-output</B>.  It sets a global variable when the
program completes.  The variable will contain any data written to stderr
by the program. <P>
The <B>-output</B> and <B>-error</B> variables are set only after the program
completes.  But if the program takes a long time, to run you may want to
receive its partial output.  You can gather data as it becomes available
using the <B>-onoutput</B> option.  It specifies a Tcl command prefix.  Whenever
new data is available, this command is executed, with the data appended
as an argument to the command. <BR>
<CODE>proc GetInfo { data } {<BR>
    puts $data<BR>
}<BR>
blt::bgexec myStatus -onoutput GetInfo du -s $dir<BR>
</CODE><P>When output is available, the procedure <I>GetInfo</I> is called. The <B>-onerror</B> option
performs a similar function for the stderr data stream. <P>
Like <B>exec</B>, <B>bgexec</B>
returns an error if the exit code of the program is not zero.  If you think
you may get a non-zero exit code, you might want to invoke <B>bgexec</B> from within
a <B>catch</B>. <BR>
<CODE>catch { blt::bgexec myStatus -output myOutput du -s $dir }<BR>
</CODE><P>By default, <B>bgexec</B> will wait for the program to finish. But you can detach
the program making ampersand (&amp;) the last argument on the command line. <BR>
<CODE>global myStatus myOutput<BR>
blt::bgexec myStatus -output myOutput du -s $dir &amp;<BR>
</CODE><P><B>Bgexec</B> will return immediately and its result will be a list of the spawned
process ids.  If at some point you need to wait for the program to finish
up, you can use <B>tkwait</B>.  When the program finishes, the variable <I>myStatus</I>
will be written to, breaking out the <B>tkwait</B> command. <BR>
<CODE>global myStatus myOutput<BR>
blt::bgexec myStatus -output myOutput du -s $dir &amp;<BR>
<tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;...<BR>
tkwait variable myStatus<BR>

<H2><A NAME="sect5" HREF="#toc5"></CODE><P>Syntax</A></H2>
The <B>bgexec</B> command takes the following form: <P>
<B><tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;blt::bgexec <I>varName</I></B>
?<I>option value</I>?... <I>program</I> ?<I>arg</I>?... <P>
<I>VarName</I> is the name of a global variable which
is set when  <I>program</I> has finished executing.  The exit status of will be
stored in <I>varName</I>.  The exit status is a list of a status token, the process-id
of the program, the exit code, and a status message.  You can also prematurely
terminate the program by setting <I>varName</I>.  Under Unix, the program will
be sent a signal to terminate it (by default the signal is a SIGKILL; see
the <B>-killsignal</B> option). <P>
<I>Program</I> is the name of the program to be executed
and <I>args</I> are any extra arguments for <I>program</I>.  The syntax of <I>program</I> and
<I>args</I> is the same as the <B>exec</B> command. So you can redirect I/O, execute pipelines,
etc. (see the <B>exec</B> manual for further information) just like <B>exec</B>.  If the
last argument is an ampersand (&amp;), the program will be run detached, and
<B>bgexec</B> will return immediately.  <I>VarName</I> will still be set with the return
status when <I>program</I> completes. 
<H2><A NAME="sect6" HREF="#toc6">Options</A></H2>
<I>Option</I> refers to the switch name always
beginning with a dash (-). <I>Value</I> is the value of the option.  Option-value
pairs are terminated either by the program name, or double dashes (--). The
following options are available for <B>bgexec</B>: 
<DL>

<DT><B>-decodeerror <I>encodingName</I></B>  </DT>
<DD><BR>
Specifies the encoding of the stderr channel. This affects only data returned
to the Tcl interpreter.  No translation  is done on file redirection. <BR>
For example if data is to be converted from Unicode for use in Tcl, you
would use the "unicode" encoding. The default is that no  translation is
performed. </DD>

<DT><B>-decodeoutput <I>encodingName</I></B>  </DT>
<DD><BR>
Specifies the encoding of the stdout channels. This affects only data returned
to the Tcl interpreter.  No translation  is done on file redirection. <BR>
For example if data is to be converted from Unicode for use in Tcl, you
would use the "unicode" encoding. The default is that no  translation is
performed. </DD>

<DT><B>-error <I>varName</I></B>  </DT>
<DD><BR>
Specifies that a global variable <I>varName</I> is to be set with the contents
of stderr after the program has completed.  </DD>

<DT><B>-keepnewline <I>boolean</I></B> </DT>
<DD>Specifies
that a trailing newline should be retained in the  output. If <I>boolean</I> is
true, the trailing newline is truncated from the output of the <B>-onoutput</B>
and <B>-output</B> variables.   The default value is <I>true</I>. </DD>

<DT><B>-killsignal <I>signal</I></B> </DT>
<DD>Specifies
the signal to be sent to the program when  terminating. This is available
only under Unix.  <I>Signal</I> can either be a number (typically 1-32) or a mnemonic
(such as SIGINT). If <I>signal</I> is the empty string,  then no signal is sent.
 The default signal is <I>9</I> (SIGKILL). </DD>

<DT><B>-lasterror <I>varName</I></B> </DT>
<DD>Specifies a variable
<I>varName</I> that is updated whenever data becomes available from standard error
of the program. <I>VarName</I> is a global variable. Unlike the <B>-error</B> option, data
is available as soon as it arrives. </DD>

<DT><B>-lastoutput <I>varName</I></B>  </DT>
<DD>Specifies a variable
<I>varName</I> that is updated whenever data becomes available from standard output
of the program. <I>VarName</I> is a global variable. Unlike the <B>-output</B> option, data
is available as soon as it arrives. </DD>

<DT><B>-linebuffered <I>boolean</I></B> </DT>
<DD>Specifies that
updates should be made on a line-by-line basis. Normally when new data is
available <B>bgexec</B> will set the variable (<B>-lastoutput</B> and <B>-lasterror</B> options)
or invoke the command (<B>-onoutput</B> and <B>-onerror</B> options) delivering all the
new data currently available.  If <I>boolean</I> is true, only one line at a time
will be delivered.  This can be useful when you want to process the output
on a line-by-line basis.   The default value is <I>false</I>. </DD>

<DT><B>-output <I>varName</I></B> </DT>
<DD><BR>
Specifies that a global variable <I>varName</I> is to be set with the output of
the program, once it has completed.  If this option  is not set, no output
will be accumulated. </DD>

<DT><B>-onerror <I>command</I></B> </DT>
<DD>Specifies the start of a Tcl command
that will be executed whenever new data is available from standard error.
The data is appended to the command as an extra argument before it is executed.
</DD>

<DT><B>-onoutput <I>command</I></B>  </DT>
<DD>Specifies the start of a Tcl command that will be executed
whenever new data is available from standard output. The data is appended
to the command as an extra argument before it is executed. </DD>

<DT><B>-update <I>varName</I></B>
 </DT>
<DD>Deprecated. This option is replaced by <B>-lasterror</B>. </DD>

<DT><B>--</B> </DT>
<DD>This marks the end of
the options.  The following argument will be considered the name of a program
even if it starts with  a dash (<B>-</B>). </DD>
</DL>

<H2><A NAME="sect7" HREF="#toc7">Preemption</A></H2>
Because <B>bgexec</B> allows Tk to
handle events while a program is running, it's possible for an application
to preempt itself with further user-interactions.  Let's say your application
has a button that runs the disk usage example.  And while the <I>du</I> program
is running, the user accidently presses the button again.  A second <B>bgexec</B>
program will preempt the first.  What this means is that the first program
can not finish until the second program has completed. <P>
Care must be taken
to prevent an application from preempting itself by blocking further user-interactions
(such as button clicks).  The BLT <B>busy</B> command is very useful for just these
situations. See the <B>busy</B> manual for details. 
<H2><A NAME="sect8" HREF="#toc8">Differences with Fileevent</A></H2>
Since
Tk 4.0, a subset of <B>bgexec</B> can be also achieved using the <B>fileevent</B> command.
 The steps for running a program in the background are: <P>
Execute the program
with the <B>open</B> command (using the "|" syntax) and save the file handle. <BR>
<CODE>global fileId <BR>
set fileId [open "|du -s $dir" r]<BR>
</CODE><P>Next register a Tcl code snippet with <B>fileevent</B> to be run whenever output
is available on the file handle.  The code snippet will read from the file
handle and save the output in a variable. <BR>
<CODE>fileevent fileId readable { <BR>
    if { [gets $fileId line] &lt; 0 } {<BR>
<tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;close $fileId<BR>
<tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;set output $temp<BR>
<tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;unset fileId temp<BR>
    } else {<BR>
<tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;append temp $line<BR>
    }<BR>
}<BR>
<P>
</CODE><P>The biggest advantage of <B>bgexec</B> is that, unlike <B>fileevent</B>, it requires
no additional Tcl code to run a program.  It's simpler and less error prone.
 You don't have to worry about non-blocking I/O. It's handled transparently
for you. <P>
<B>Bgexec</B> runs programs that <B>fileevent</B> can not. <B>Fileevent</B> assumes that
the when stdout is closed the program has completed.  But some programs,
like the Unix <I>compress</I> program, reopen stdout, fooling <B>fileevent</B> into thinking
the program has terminated.  In the example above, we assume that the program
will write and flush its output line-by-line.  However running another program,
your application may block in the <B>gets</B> command reading a partial line. <P>
<B>Bgexec</B>
lets you get back the exit status of the program. It also allows you to
collect data from both stdout and stderr simultaneously. Finally, since
data collection is handled in C code, <B>bgexec</B> is faster. You get back to
the Tk event loop more quickly, making your application seem more responsive.

<H2><A NAME="sect9" HREF="#toc9">See Also</A></H2>
busy, exec, tkwait 
<H2><A NAME="sect10" HREF="#toc10">Keywords</A></H2>
exec, background, busy <P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Syntax</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Options</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Preemption</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Differences with Fileevent</A></LI>
<LI><A NAME="toc9" HREF="#sect9">See Also</A></LI>
<LI><A NAME="toc10" HREF="#sect10">Keywords</A></LI>
</UL>
</BODY></HTML>
blt-dev 2.5.3+dfsg-1 / usr / share / doc / blt-dev / html / bgexec.html
