quisp: shell command interface

quick server pages
| Manual page for shell(command)

## 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`.``

## @PROJDIR

The variable `@PROJDIR`, which is set in your project config file, contains the full path name of the project directory and may be used to build shell commands that reference files therein.``

## @HTMLPATH

The variable `@HTMLPATH`, which is set in your project config file, contains the full path name of the directory on your system where static files such as images reside. It may be useful when issueing shell commands.``

## 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

quick server pages
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` June 01, 2005.