shell command interface


Version 2.41 Mar2009

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: Before using #shell/#endshell in a network programming environment, developers must understand the potential for security breaches, and realize that best practice is to avoid using untrusted-user-supplied values when building shell commands. But since quisp does allow execution of shell commands, as a safety precaution it performs automatic removal of hazardous shell metacharacters present in variables that are evaluated within the #shell / #endshell construct. The following are automatically removed when QUISP variables are evaluated within a #shell / #endshell construct: " ' ` $ \ ; | ../ (this was updated with patch 1.27-01 ). The set of filtered metacharacters is configurable via config file or #mode command. Developers that choose to use this feature are responsible for ensuring that the metacharacter screening feature is operating as expected. Enclosing all shell command line arguments in quotes may provide an extra measure of protection.

QUISP's internal mechanism for invoking shell commands uses popen(3C).


#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, (but #sql directives cannot be intermingled). 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. If not specified, #dump will be the default.

#dump - execute the shell command and write the results directly to standard output. This is the default.

#processrows - execute the shell command. The application must then fetch individual result lines using the $shellrow() function (see below).

#dumptab - execute the shell command, parse result lines into fields, and write fields to standard output delimited by tabs.

#dumphtml - execute the shell command, parse result lines into fields, and write to standard output as HTML table rows.

#dumpsilent - execute the shell command, but don't display result lines at all. However a row count can be gotten by calling the $shellrowcount function (see below).




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. When there are no more result lines, the result variables are all set to "". (But if the shell command produces no results, the result variables are not set at all.)
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( delimtype )

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. The delimtype argument indicates delimitation of field name header and data; it may be given as tab or whitespace; if omitted, whitespace is assumed.
Example:
  #shell
    mycommand
  #endshell
  #call $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


Ploticus is hosted at http://ploticus.sourceforge.net   Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads


Markup created by unroff 1.0,    March 11, 2009.