Shell command interface

#shell - #endshell

Usage:

   #shell [mode]
      shellcommand(s)
      ...
   #endshell

mode may be one of the following:

dump - write the results directly to standard output. This is the default.

processrows - individual result lines will be available via the $shellrow() function.

dumptab - result lines are parsed into fields and written to standard output delimited by tabs.

dumphtml - result lines are parsed into fields and written to standard output as HTML table rows.

dumpsilent - don't display result lines at all, but row count will be available via $shellrowcount.

Note: mode may optionally begin with a pound sign (#) for readability.

Note: #sql directives cannot be embedded within #shell / #endshell.

Functions

$shellrow( fieldname1, .., fieldnameN )

Get the next line of shell command results and parse into fields. Result fields are loaded into variables that use names fieldname1 .. fieldnameN. Returns 0 on success, 1 if no more result lines, or an error code > 1.

If only one fieldname is given, the entire result line will be loaded. If two or more fieldnames are given, result fields will be delimited on whitespace by default, or TAB if $shellfielddelim( tab ) was called previously, and individual fields will be loaded into variables. If $shellreadheader() was called initially to read a result field name header then no fieldnames should be given with $shellrow().

You can also use this function to capture tag: value result lines; to do this, use $shellrow( #varvaluepair ), and values will be loaded into variables named using the tag.

$shellrowcount( )

Return the number of result rows produced by the most recently invoked shell command.

$shellexitcode( )

Return the final exit code of the most recently invoked shell command.

$shellfielddelim( s )

Set the delimitation method for parsing shell command result fields. Allowable values for s are tab, whitespace, or line (which takes the entire line, without trailing newline, as a field).

Example: #call shellfielddelim( whitespace )

$shellreadheader( )

For shell commands that produce output where the first line contains field names, this function can be used to load the header. Afterwards, $shellrow(), if it is passed no arguments, will load fields into variables based on the header.

Example:

  #shell
    mycommand
  #endshell
  #shellreadheader()
  #while $shellrow() = 0
    ...

Examples

Example 1. Invoke a grep command and display the results:

   #set searchword = "macula"
   <pre>
   #shell 
     grep "@searchword" /home/steve/textfiles/*
   #endshell
   </pre>
   #if $shellrowcount() != 0
    <h3>Nothing found</h3>
   #endif

Example 2. Same as above but add a sed command and display results as HTML table rows:

   #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

Example 3. Invoke a command that computes correlations and process the results one row at a time:

    #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

Example 4. Invoke a shell command and capture its exit code:

    #shell
      addlog @DATE @TIME @READING
    #endshell
    #if $shellexitcode() != 0
      <h3>Addlog failed!</h3>
    #endif