#set TITLE = "Using #shell and #sql in ploticus scripts

#include top

.SH #shell and #sql
These are two new directives that can be used in scripts with ploticus 2.00
and higher.  They both work similary, and can either stream results into
the script, or set variables.  
#set FILE = shell.html
#set TAG = "#shell"
#include link
is an interface for running external commands and capturing the results.
#set FILE = sql.html
#set TAG = "#sql"
#include link
will allow ploticus to operate as a client to SQL databases, and works with
pocketSQL.  
Interface to other databases (MySQL, Oracle, etc.) is not yet available;
code contributions are sought in these areas (see \fCdbinterface.c\fR).

#include space

.SH STREAMING DATA
Here is an example of how 
#set FILE = sql.html
#set TAG = "#sql"
#include link
is to be used with 
#set FILE = getdata.html
#set TAG = "proc getdata"
#include link
:
.nf
\0	#proc getdata
\0	delim: tab
\0      data:
\0	#sql #dumptab select * from trialresults where trialnum = @TRIALNUM
.fi
.LP
For longer SQL commands a multi-line construct is available:
.nf
\0	#proc getdata
\0	delim: tab
\0      data:
\0	#sql #dumptab 
\0		select trialnum, age, sex, weight, time1, time2
\0		 from trialresults 
\0		where trialnum = @TRIALNUM and trialdate = @TDATE
\0      #endsql
.fi
The
#set FILE = shell.html
#set TAG = "#shell"
#include link
directive can be used similary, but this is redundant since 
#set FILE = getdata.html
#set TAG = "proc getdata"
#include link
already has a \fCcommand\fR attribute.

#include space

.SH SETTING VARIABLES
These directives may be used to set variables for plot labels, etc.
For example:
.nf
\0	#sql #load select fullname from tsyms where tickersym = @TSYM
\0
\0      #proc annotate
\0      location: min max-0.2
\0      text: @fullname
\0
.fi
.LP
Here is an example where the results of a shell command may be used to
set variables:
.nf
\0      // submit the command..
\0      #shell #processrows cat mydata | grep "^Jan"
\0      // get one result rows and parse out fields..
\0      #call $shellrow( A, B, C ) 
\0
\0	#proc annotate
\0	location: min max-0.2
\0	text: @A @B

#include space

.SH DRIVING LOOPS
These directives may be used to drive loops that iterate once per
row of results.  For example:
.nf
\0	// get a list of cases
\0	#sql #processrows select caseid from cases
\0	#while $sqlrow() = 0
\0	  // get data for a case
\0	  #proc getdata
\0	  delim: tab
\0	  data:
\0	    #sql2 #dumptab select * from casedata where caseid = @caseid
\0	    ... plot the case
\0
\0	#endloop
.fi
.LP
#set FILE = shell.html
#set TAG = "#shell"
#include link
may be used similary.

#include bottom
