ploticus: shell command interface

## shell command interface | Welcome Gallery Handbook |
| Manual page for shell_command_interface(PL)

## Shell command interface

midriff provides a convenient facility for invoking shell commands and capturing/parsing the results, for maximum flexibility in interfacing with the shell and other programs.`` Developers should fully understand the security issues involved when building shell commands from CGI user variables.`` Several examples are provided below.``

## #shell - #endshell

Issue a shell command.`` The shell command can be one or more lines in length.`` midriff variables and other directives such as `#if` can be used to build the shell command.`` Results can be displayed directly or captured for further processing.`` The shell command's exit code is available via $shellexitcode() and the number of output lines is available via $shellrowcount().`` midriff variables that are present in the shell command are automatically screened for shell metacharacters as a security precaution.``

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

These functions may be used in conjunction with the `#shell` command:

$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

data display engine
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` December 10, 2002.