## shell command interface

Version 2.32
Scripts

Manual page for shell_command_interface(PL)

## Shell command interface

The #shell 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 examples are provided below.``

Security concern: avoid using user-supplied values (such as CGI user variables, or variables derived from them) when building shell commands (hackers can do things like drop in `|id|` or `|telnet ..|`). Where there's no alternative, #shell / #endshell provides automatic removal of hazardous shell metacharacters present in variables that are evaluated within the `#shell / #endshell` construct. The developer should verify that this is working as expected.`` The following are automatically removed when QUISP variables are evaluated within a #shell / #endshell construct: `" ' ` $ \ ; | ../` (this was updated with patch 1.27-01 ).`` This set of characters is configurable and also settable dynamically using #mode.`` For this same reason it is also good practice to enclose all shell command arguments in double quotes.`` Developers must understand this potential security hole and verify that shell metacharacter screening is indeed working as they want it to, in their application.``

## #shell - #endshell

Issue a shell command.`` The shell command can be one or more lines in length.`` QUISP 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().``

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 )`

$shellfieldconvert( convertmode )

  Perform conversions on shell command result fields.`` Currently the only supported `convertmode` is `shsql`, 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).``

  Example: `#call $shellfieldconvert( shsql )`

$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. Get a numeric value out of the last line of a file and multiply it by 1.25:

      #shell processrows
        tail -1 today.dat | cut -f 3
      #endshell
      #call $shellrow(TODAY_TOTAL)
      #set MAX = $arith(@TODAY_TOTAL*1.25)

Example 2. 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 3. 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 4. 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 5. 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, `` `` August 23, 2005.