shell command interface


Version 2.30

Scripts


Manual page for shell_command_interface(PL)

Shell command interface

The #shell directive provides a convenient, safe 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.

To address the security problem of malicious users executing nasty shell commands via cgi variables, the following shell metacharacters are automatically screened out from QUISP variables that are present in the shell command: " ' ` $ \ ; (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.


Most of the rest of this page isn't very applicable in the ploticus context..





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 25, 2004.