<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../style.css">
<title>
Gambas Documentation - EXEC
</title>
</head>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../help+en"><img class="flag" alt="Home" border="0" src="../../img/lang/en.png" align="center"></a>&nbsp;
<a href="../lang+en">Up</a>&nbsp;
<a href="eventdecl+en">Previous</a>&nbsp;
<a href="exist+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
EXEC
</h1>
<div class="black"><font size="-2"><b>Syntax</b></font></div>
<pre class="syntax">[ <u>Process</u> <b>=</b> ] <b>EXEC</b> <u>Command</u> [ <b>WAIT</b> ] [ <b>FOR</b> { { <b>READ</b> | <b>INPUT</b> } | { <b>WRITE</b> | <b>OUTPUT</b> } } ] [ <b>AS</b> <u>Name</u> ]<br>
<b>EXEC</b> <u>Command</u> <b>TO</b> <u>Variable</u></pre><p>

Executes a command. An internal <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> is created to manage the command.
<p>
The command must be specified as an array of strings containing at least one element. The first element of this array is the name of the command, and the others are optional parameters.
<p>
<ul>
<li>If <tt><b>WAIT</b></tt> is specified, then the interpreter waits for the command ending. Otherwise, the command is executed in background.
<p>
<li>If <tt><b>FOR</b></tt> is specified, then the command input-outputs are redirected so that your program intercepts them:
<p>
<ul>
<li>If <tt><b>WRITE</b></tt> is specified, you can send data to the command standard input by using the <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> with common output instructions: <a href="print+en">PRINT</a>, <a href="write+en">WRITE</a>, ... Note that you need a reference to the <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> for that.
<p>
<li>If <tt><b>READ</b></tt> is specified, then events will be generated each time the command sends data to its standard output <a href="../def/stream+en">stream</a>: the event <a href="../comp/gb/process/_read+en">Read</a> is raised when data are sent to the standard output <a href="../def/stream+en">stream</a>, and the event <a href="../comp/gb/process/_error+en">Error</a> is raised when data are sent to the standard error <a href="../def/stream+en">stream</a>. Use the process <a href="../def/object+en">object</a> with <a href="../cat/stream+en">Stream &amp; Input/Output functions</a> to read the process standard output:.
<p>
</ul>
</ul>

If you use the <tt><b>INPUT</b></tt> and <tt><b>OUTPUT</b></tt> keywords instead of <tt><b>READ</b></tt> and <tt><b>WRITE</b></tt>, then the process is executed inside a virtual terminal. It means that the process will think running inside a true terminal.
<p>
<tt><u>Name</u></tt> is the event name used by the <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a>. By default, it is <tt>&quot;Process&quot;</tt>.
<p>
You can get a reference to the internal <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> created by using an assignment.
<p>
If you use the second syntax, the command is executed, the interpreter waiting for its end, and the complete command output is put in the specified string.
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' Get the contents of a directory
EXEC [ &quot;ls&quot;, &quot;-la&quot;, &quot;/tmp&quot; ] WAIT</pre>
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' Get the contents of a directory into a string
DIM sOutput AS String
EXEC [ &quot;ls&quot;, &quot;-la&quot;, &quot;/tmp&quot; ] TO sOutput</pre>
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' Get the contents of a directory into a string, but in background

DIM sOutput AS String

' A specific event name is used
EXEC [ &quot;ls&quot;, &quot;-la&quot;, &quot;/tmp&quot; ] FOR READ AS &quot;Contents&quot;

...

PUBLIC SUB Contents_Read()

  DIM sLine AS String

  READ #LAST, sLine, -256

  sOutput &= sLine

END

PUBLIC SUB Contents_Kill()

  PRINT sOutput

END</pre>
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/info.png" align="center"></td><td valign="top">
If you want to know how many bytes you can read in a <tt>Process_Read</tt> event handler, use the <a href="lof+en">Lof</a> function.
</td></tr></table></div>
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/info.png" align="center"></td><td valign="top">
As arguments are sent directly to the process, you do not have to quote them, as you must do in a shell.
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' perl -e 'print while <>;' becomes

EXEC [ &quot;perl&quot;, &quot;-e&quot;, &quot;print while <>;&quot; ] FOR READ WRITE</pre>
</td></tr></table></div>
<p>
<hr><b>See also</b><br>
<a href="../cat/process+en">Process Management</a>&nbsp; <a href="../comp/gb/process+en">Process</a>&nbsp; <a href="lof+en">Lof</a>&nbsp;

</div>
</body>
</html>

