<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/11/09 12:56:22. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
A:link{text-decoration:none}
A:visited{text-decoration:none}
A:active{text-decoration:none}
OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }
H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: shell command interface</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550><tr>
<td>
<table cellpadding=2 width=550><tr>
<td><br><h2>shell command interface</h2></td>
<td align=right>
<small>
<a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
Version 2.41 Mar2009
</small><br><a href="../doc/scripthome.html">Scripts</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for shell_command_interface(PL)</title>
</head>
<body>
<h2>Shell command interface</h2>
The <b>#shell</b> directive
provides a convenient facility for invoking shell commands and
capturing/parsing the results, for maximum flexibility in interfacing
with the shell and other programs.
Several
<a href="#examples">
examples
</a>
are provided below.<tt> </tt>
<p>
<b>Security concern:</b>
Before using #shell/#endshell in a network programming environment, developers must understand the potential for
security breaches, and realize that best practice is to avoid using untrusted-user-supplied values when building shell
commands. But since quisp does allow execution of shell commands, as a safety precaution it
performs automatic removal of hazardous shell metacharacters present in
variables that are evaluated within the <tt>#shell / #endshell</tt> construct.
The following are automatically removed when QUISP variables
are evaluated within a #shell / #endshell construct: <tt> " ' ` $ \ ; | ../ </tt>
(this was updated with
<a href="../../download">
patch 1.27-01
</a>
).<tt> </tt>
The set of filtered metacharacters is configurable via
<a href="config.html">
config file
</a>
or
<a href="mode.html">
#mode command.<tt> </tt>
</a>
Developers that choose to use this feature are responsible for ensuring that the
metacharacter screening feature is operating as expected.<tt> </tt>
Enclosing all shell command line arguments in quotes may provide an extra measure of protection.<tt> </tt>
<p>
QUISP's internal mechanism for invoking shell commands uses <tt>popen(3C)</tt>.<tt> </tt>
<br><br><br>
<h2>#shell - #endshell</h2>
Issue a shell command.<tt> </tt>
The shell command can be one or more lines in length.<tt> </tt>
QUISP variables and other directives such as <tt>#if</tt> can be used to build the shell command,
(but <tt>#sql</tt> directives cannot be intermingled).<tt> </tt>
Results can be displayed directly or captured for further processing.<tt> </tt>
The shell command's exit code is available via
<a href="#functions">
$shellexitcode()
</a>
and the number of output lines is available via
<a href="#functions">
$shellrowcount().<tt> </tt>
</a>
<p>
Usage:
<pre>
#shell [<i>mode</i>]
<i>shellcommand(s)</i>
...
#endshell
</pre>
<p>
<b>mode</b> may be one of the following. If not specified, #dump will be the default.<tt> </tt>
<dl>
<dt><dd><p>
<b>#dump</b> - execute the shell command and write the results directly to standard output. This is the default.<tt> </tt>
<dt><dd><p>
<b>#processrows</b> - execute the shell command. The application must then fetch individual result lines using the <tt>$shellrow()</tt>
function (see below).<tt> </tt>
<dt><dd><p>
<b>#dumptab</b> - execute the shell command, parse result lines into fields, and write fields to standard output delimited by tabs.<tt> </tt>
<dt><dd><p>
<b>#dumphtml</b> - execute the shell command, parse result lines into fields, and write to standard output as HTML table rows.<tt> </tt>
<dt><dd><p>
<b>#dumpsilent</b> - execute the shell command, but don't display result lines at all. However a row count can be gotten by calling
the <tt>$shellrowcount</tt> function (see below).<tt> </tt>
</dl>
<p>
<br><br><br>
<a name=functions></a>
<h2>Functions</h2>
These functions may be used in conjunction with the <tt>#shell</tt> command:
<br><br>
<p>
<b>$shellrow( fieldname1, .., fieldnameN )</b>
<dl>
<dt> <dd>
Get the next line of shell command results and parse into fields.<tt> </tt>
Result fields are loaded into variables that use names <i>fieldname1 .. fieldnameN</i>.<tt> </tt>
Returns 0 on success, 1 if no more result lines, or an error code > 1.<tt> </tt>
When there are no more result lines, the result variables are all set to "".<tt> </tt>
(But if the shell command produces no results, the result variables are not set at all.)
<dt> <dd>
If only one fieldname is given, the entire result line will be loaded.<tt> </tt>
If two or more fieldnames are given, result fields will be delimited on whitespace by default,
or TAB if <tt>$shellfielddelim( tab )</tt> was called previously, and individual fields will be
loaded into variables.<tt> </tt>
If <tt>$shellreadheader()</tt> was called initially to read a result field name header then
no fieldnames should be given with <tt>$shellrow()</tt>.<tt> </tt>
<dt> <dd>
You can also use this function to capture <tt>tag: value</tt> result lines; to do this, use
<tt>$shellrow( #varvaluepair )</tt>, and values will be loaded into variables named using the tag.<tt> </tt>
<br><br><br>
</dl>
<p>
<b>$shellrowcount( )</b>
<dl>
<dt> <dd>
Return the number of result rows produced by the most recently invoked shell command.<tt> </tt>
<br><br><br>
</dl>
<p>
<b>$shellexitcode( )</b>
<dl>
<dt> <dd>
Return the final exit code of the most recently invoked shell command.<tt> </tt>
<br><br><br>
</dl>
<p>
<b>$shellfielddelim( s )</b>
<dl>
<dt> <dd>
Set the delimitation method for parsing shell command result fields.<tt> </tt>
Allowable values for <i>s</i>
are <tt>tab</tt>, <tt>whitespace</tt>, or <tt>line</tt> (which takes the entire
line, without trailing newline, as a field).
<dt> <dd>
Example: <tt>#call shellfielddelim( whitespace )</tt>
<br><br><br>
</dl>
<p>
<b>$shellfieldconvert( convertmode )</b>
<dl>
<dt><dd><p>
Perform conversions on shell command result fields.<tt> </tt>
Currently the only supported <tt>convertmode</tt> is <tt>shsql</tt>,
which causes conversions useful when using shell commands to process
shsql data files (nulls are converted to zero-length strings, and
embedded underscores are converted to spaces).<tt> </tt>
<dt> <dd>
Example: <tt>#call $shellfieldconvert( shsql )</tt>
<br><br><br>
</dl>
<p>
<b>$shellreadheader( delimtype )</b>
<dl>
<dt> <dd>
For shell commands that produce output where the first line contains field names,
this function can be used to load the header. Afterwards, <tt>$shellrow()</tt>,
if it is passed no arguments, will load fields into variables based on the header.<tt> </tt>
The <i>delimtype</i> argument indicates delimitation of field name header and data;
it may be given as <tt>tab</tt> or <tt>whitespace</tt>; if omitted, <tt>whitespace</tt> is assumed.<tt> </tt>
<dt> <dd>
Example:
<pre>
#shell
mycommand
#endshell
#call $shellreadheader()
#while $shellrow() = 0
...
</pre>
<br><br><br>
<a name=examples></a>
</dl>
<h2>Examples</h2>
<p>
<b>Example 1. Get a numeric value out of the last line of a file and multiply it by 1.25:</b>
<pre>
#shell #processrows
tail -1 today.dat | cut -f 3
#endshell
#call $shellrow(TODAY_TOTAL)
#set MAX = $arith(@TODAY_TOTAL*1.25)
</pre>
<b>Example 2. Invoke a grep command and display the results:</b>
<pre>
#set searchword = "macula"
<pre>
#shell
grep "@searchword" /home/steve/textfiles/*
#endshell
</pre>
#if $shellrowcount() != 0
<h3>Nothing found</h3>
#endif
</pre>
<p>
<b>Example 3. Same as above but add a sed command and display results as HTML table rows:</b>
<pre>
#set searchword = "macula"
<table cellpadding=2>
#shell #dumphtml
grep "@searchword" /home/steve/textfiles/* |
sed "s/^.*://"
#endshell
</table>
#if $shellrowcount() != 0
<h3>Nothing found</h3>
#endif
</pre>
<p>
<b>Example 4. Invoke a command that computes correlations and process the results one row at a time:</b>
<pre>
#shell #processrows
correlate all
#endshell
<table cellpadding=2>
#while $shellrow( var1, var2, pearson, n ) == 0
<tr><td>@var1</td><td>@var2</td><td>@pearson</td><td>N = @n</td></tr>
#endloop
</table>
#if $shellrowcount() < 1
<h3>No correlations computed</h3>
#endif
</pre>
<p>
<b>Example 5. Invoke a shell command and capture its exit code:</b>
<pre>
#shell
addlog @DATE @TIME @READING
#endshell
#if $shellexitcode() != 0
<h3>Addlog failed!</h3>
#endif
</pre>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<br>
<center>
<table><tr><td>
Ploticus is hosted at http://ploticus.sourceforge.net</td><td> </td><td>
<a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12"
width="120" height="30" border="0"
alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td></tr></table>
</center>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009.
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ed05dc5f357c49fdded780f52b150dce
>
files
>
112
