#set TITLE = SQL
#include top

.SH NAME
\fC#sql [\fIoption\fC]  \fIsql command\fC  [#endsql]\fR

#include space

.SH DESCRIPTION
This directive allows SQL code to be embedded in scripts, and
submits the embedded SQL code to your database.
.LP
For SQL SELECT commands, an \fIoption\fR may be given; available
options (described below) are \fC#load\fR, \fC#processrows\fR, and several variations of
\fC#dump\fR.  
If no \fIoption\fR is given, \fC#processrows\fR is the default.
No option should be used with SQL INSERT, UPDATE, or DELETE.
.LP
\fIsql command\fR may use a single line construct or a
multi-line construct formatted as in examples 2 or 3 below.  
\fC#endsql\fR must be used to terminate a multi-line construct.
.LP
For all SQL commands except SELECT,
the status of the command execution will be available in 
the @_STATUS script variable (0 indicates success).
.LP
Two separate SQL database connections are available.  For connection 1,
use \fB#sql\fR; for connection 2, use \fB#sql2\fR instead of \fB#sql\fR
(all other syntax is the same).  When using the SQL functions
the connection may be specified using the \fCdbc\fR parameter (see below).
#if @PL = 1
.LP
  #set FILE = plshellsql.html
  #set TAG = "Using #sql in ploticus scripts"
  #include link
#endif

#include space

.SH EXAMPLES
Example 1:
.IP
\fC#sql insert into transactions values ( "TR6824", 155.43, "K" )\fR

.LP
Example 2 shows the proper way to set up a multi-line construct:
.IP
.nf
\0#sql 
\0  update transactions
\0  set amount = 158.23, type = "P"
\0  where tracknum = "@TNUM"
\0#endsql
.fi
.LP
Example 3 will load all retrieved fields as script variables.
It uses the 2nd database connection.
Query should retrieve one row.
.IP
.nf
\0#sql2 #load
\0  select * from people where people_id = @people_id
\0#endsql
.fi
.LP
Example 4 is like above except written as a single line:
.IP
\fC#sql2 #load select name as venue from venues where venue_id = @v\fR
.LP

#include space

.SH OPTIONS
For SQL SELECT commands that produce results, an \fIoption\fR
may be specified to specify how the results will be displayed 
or captured.  If no \fIoption\fR is given \fC#processrows\fR
is performed.
The \fIoption\fRs all begin with pound sign (#) to distinguish them
from SQL command content. 
.LP
\fB#load\fR
.IP
The retrieved fields will be loaded as script variables.
Query should retrieve one row; if it retrieves multiple rows the first one
will be used.
If the query got no results, the variables will be set to a zero length string ("").
The following example would set script variables username and pw to the
retrieved values:
.nf
\0#sql #load 
\0select username, password as pw 
\0 from users 
\0 where session_id = "@SESS_ID"
\0#endsql
.fi

.LP
\fB#dumptab\fR
.IP
All rows of results will be streamed in tab-delimited format.  
Example:
.nf
\0#sql #dumptab select prog_id, prog_name from proglist
.fi

.LP
\fB#dumphtml\fR
.IP
All rows of results will be streamed in HTML table format.  
Example:
.nf
\0#sql #dumphtml select * from venues
.fi

.LP
\fB#dump\fR
.IP
All rows of results will be streamed with no automatic field separation.
The SQL SELECT command must supply any necessary field separation.
Example:
.nf
\0#sql #dump select id, "	", lastname, ", ", firstname from people
.fi

.LP
\fB#dumpsilent\fR
.IP
All rows of results will be retrieved then discarded.  Used to
get a count of the number of rows.
Example:
.nf
\0#sql #dumpsilent select * from venues
\0#set N = $sqlrowcount()
.fi

.LP
\fB#processrows\fR
.IP
Indicates that results will be retrieved and processed later one row at a time
using the \fC$sqlrow()\fR function (see below).
When processing rows, retrieved fields are available as script variables
(if a name has an embedded periods (.) these are converted to underscores
since script variable names cannot contain periods).
Example:
.IP
.nf
	// submit the sql command..
\0	#sql #processrows
\0	  select meascode, measdesc, value from mstats 
\0	  where project_id = @PROJID
\0	#endsql
\0
\0	// get the result rows..
\0	#while $sqlrow = 0
\0	  // access the fields as variables..
\0	  #if @meascode like A*
\0	    ... etc...
\0
\0	#endloop
.fi

#include space

.SH SQL-RELATED FUNCTIONS
There are several SQL-related functions.
All of them take \fCdbc\fR as an optional 
first argument.  \fCdbc\fR specifies the database connection.
Two database connections are available.  They are identified as 
\fC1\fR and \fC2\fR.  If \fCdbc\fR is omitted, connection# \fC1\fR
is assumed.


.LP
\fB$sqlrow( dbc )\fR
.IP
Retrieve next row of results.  After this is called, result fields
will be accessible by @name.  
NULL fields will be converted to "".
Returns 0 to indicate success, 1 to
indicate no row retrieved and no more rows, or an error code.
.br
Example: \fC#call $sqlrow()\fR
.br
Example: \fC#call $sqlrow( 2 )\fR

.LP
\fB$sqlrowcount( dbc )\fR
.IP
Return number of rows retrieved/affected by most recently executed
sql command.  The exact behavior of row count may depend on
the type of database being used. 
.IP
With 
#set FILE = pocketsql.html
#set TAG = "pocketSQL
#include link
, the row count is available immediately after an
#set FILE = sql.html
#set TAG = "#sql
#include link
executes.  This row count is exact except when SELECT is used with 
DISTINCT or LIMIT and result rows are retrieved individually
using $sqlrow() in which case the count will be exact after all rows have been retrieved.
.IP
Example: \fC#if $sqlrowcount( ) == 0\fR
.br
Example: \fC#if $sqlrowcount( 2 ) == 0\fR


.LP
\fB$sqlgetnames( dbc, outmode )\fR
.IP
Using the most recently submitted sql SELECT command,
write result field names to standard output.
\fIoutmode\fR may be \fCdumptab\fR for
tab delimited field names, or \fCdumphtml\fR for an html table row.
Returns 0 to indicate success, or a non-zero error code.
.br
Example: \fC#call $sqlgetnames( dumptab )\fR


.LP
\fB$sqlprefix( dbc, prefix )\fR
.IP
Set a prefix to be prepended to all result field names retrieved
by the next SELECT command.  This may be used to prevent result field names from
colliding with existing script variable names.
Must be used after the
#set FILE = sql.html
#set TAG = "#sql
#include link
statement and before \fC$sqlrow()\fR.
The prefix remains in effect for the current query only.
.br
Example: \fC#call $sqlprefix( "s" )\fR

.LP
\fB$sqlstripprefix( dbc, prefix )\fR
.IP
Indicates that \fIprefix\fR should be removed from
the beginning of any result field name where it appears, for example to
remove table name prefix from join results.
Must be used after the
#set FILE = sql.html
#set TAG = "#sql
#include link
statement, and before \fC$sqlrow()\fR.
Remains in effect for the current query only.
.br
Example: \fC#call $sqlstripprefix( "people." )\fR

#include space

.SH NOTES
.LP
#if @CGIPAL = 1
The default SQL database is
#set FILE = "pocketsql.html"
#set TAG = "pocketsql"
#include link
which is built-in.  
#endif //CGIPAL
Interfaces to databases are implemented in \fCdbinterface.c\fR
.LP
\fB#sql\fR cannot be intermingled with \fB#shell\fR.

#include bottom
