#set TITLE = "sql database interface"
#include top

.SH SQL database interface
The \fB#sql\fR directive
provides a convenient interface for building and invoking SQL commands, and
capturing the results.
By default \fB#sql\fR points to
#set FILE = "../../sqlman/html/shsql_home.html"
#set TAG = "SHSQL"
#include link
(which is bundled with QUISP).
#set FILE = "otherdb.html"
#set TAG = "Interfaces to other databases are also possible."
#include link
.LP
A number of
#set FILE = "#examples"
#set TAG = "#sql examples"
#include link
are provided below; see also the
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index"
#set TAG = "live demo on sourceforge."
#include link


#include space

.SH #sql - #endsql
Issue an SQL command.
The SQL command can be one or more lines in length.
Script variables and directives such as \fC#if\fR may be embedded in order to conditionally build an SQL command.
Command status is available via 
#set FILE = "#functions"
#set TAG = "$sqlerror()"
#include link
(a nonzero value indicates an error).
For \fCSELECT\fR commands, the number of retrieved rows is available via 
#set FILE = "#functions"
#set TAG = "$sqlrowcount()"
#include link
and individual result rows are retrieved using 
#set FILE = "#functions"
#set TAG = "$sqlrow()."
#include link
.LP
Usage: 
.nf
 \0 #sql [\fIichannel\fR]  [\fImode\fC]
 \0    \fIsql command\fR
 \0    ...
 \0 #endsql\fR
.fi
Alternatively, a single-line form may be used:
.br
\fC#sql [\fIichannel\fR]  [\fImode\fC]  \fIsql command\fR

.LP
\fIichannel\fR is \fC1\fR, \fC2\fR, \fC3\fR or \fC4\fR.  
When \fIichannel\fR is not specified channel 1 is assumed.
The channel number may be preceded by a pound sign \fC#\fR if desired.
Multiple channels are useful in nested contexts, eg. a retrieval on channel 1 is in progress, and
a retrieval is being done (on channel 2) for every channel 1 result row.
The database access functions below also accept a channel argument.
See example 8 below which uses channels.

.LP
\fImode\fR may be one of the following:
.IP
\fCprocessrows\fR - any result rows will be available via the \fC$sqlrow()\fR function.  This is the default.
.IP
\fCload\fR - one result row is expected, and each result field will be loaded into an appropriately-named variable.
.IP
\fCdump\fR - write the results directly to standard output.  
.IP
\fCdumptab\fR - result lines are parsed into fields and written to standard output delimited by tabs.
.IP
\fCdumphtml\fR - result lines are parsed into fields and written to standard output as HTML table rows.
.IP
\fCdumpsilent\fR - don't display result lines at all, but row count will be available via \fC$sqlrowcount()\fR.
.LP
Hint: In CGI mode, output some HTML (even if just \fC<br>\fR) before 
the \fC#sql\fR statement; this allows any error messages to be displayed
in the browser.
.LP
Note: \fImode\fR may begin with a pound sign (\fC#\fR) if desired, for readability.
.LP
Note: \fC#shell\fR directives cannot be embedded within \fC#sql\fR / \fC#endsql\fR.


.ig >>
<a name=sqlblankrow></a>
.>>

#include space

.SH #sqlblankrow
.LP
\fC#sqlblankrow \fIdbtable\fR
.LP
For every field defined in database table \fIdbtable\fR, initialize a variable to \fC""\fR.
This operator is useful when setting up a form for new content entry, where the form
fields correspond to fields in a database table.

.ig >>
<a name=sqlcgivars></a>
.>>
#include space

.SH #sqlcgivars
Get an ordinary CGI user variable for every field defined
for database table \fIdbtable\fR.
Typical use is on a form
#set FILE = "forms.html"
#set TAG = "target page;"
#include link
using \fC#sqlcgivars\fR lets you avoid having to enumerate all fields in a \fC#cgivar\fR statement.
The CGI user variable names must exactly match the database table field names.
.LP
Usage: \fC#sqlcgivars  \fIdbtable\fR  \fC[overwrite]\fR
.LP
Example: \fC#sqlcgivars  people\fR
.LP
Example: \fC#sqlcgivars  people  overwrite\fR
.LP
Unless the \fCoverwrite\fR option is given,
variables that are already in use (have already been given a value) will NOT be set
by \fC#sqlcgivars\fR.
.LP
If any of the variables need to be captured using special conversions (eg.
\fC#cgilistvar\fR, \fC#cgitextvar\fR, or \fC#cgimultivar\fR), these operators must be invoked
\fBbefore\fR \fC#sqlcgivars\fR, and the \fCoverwrite\fR option must not be used.
.LP
Caution: any fields not present in the submitted form must be passed to the target page using
#set FILE = "forms.html"
#set TAG = "#pass;"
#include link
otherwise any existing contents of those fields will be lost.


.ig >>
<a name=sqlbuild></a>
.>>
#include space
.SH #sqlbuild
Automatically builds an SQL \fCINSERT\fR command or most of an \fCUPDATE\fR command.
Traditionally in systems where SQL is submitted by middleware, the SQL command is coded manually, like in 
the INSERT command in example 5 below, and the developer must manually enumerate all fields, as well as code 
for quoting, conversion of blank fields to NULL, and escape out any embedded quotes.
.LP
If \fC#sqlbuild\fR is used, much of this work is done for you; see examples 6 and 7 below.
For UPDATE, the developer must supply a trailing where clause as shown.
\fC#sqlbuild\fR assumes that a script variable exists for each database field,
and has the same name as the database field.  
\fC#sqlbuild\fR is typically used in a
#set FILE = "cgiforms.html"
#set TAG = "form target page"
#include link
where a data record has been submitted from a form, and where the fields have
been loaded using 
#set FILE = "cgivar.html"
#set TAG = "#sqlcgivars."
#include link

.LP
Usage: \fC#sqlbuild  \fIumode  dbtable  defaultqmode\fR  [omit=\fIfields\fR]  [noquote=\fIfields\fR]  [quote=\fIfields\fR]
.IP
\fIumode\fR is either \fCinsert\fR or \fCupdate\fR (\fCnew\fR is accepted as equivalent to \fCinsert\fR).
.IP
\fIdbtable\fR is the name of the database table being updated.
.IP
\fIdefaultqmode\fR is the default quoting mode, either \fCquote\fR or \fCnoquote\fR.  Unless listed in the exceptions,
all fields are treated this way.
.IP
The \fComit=\fR parameter (optional) names fields that shouldn't be included at all.
.IP
The \fCnoquote=\fR parameter (optional) names fields that shouldn't be quoted, for when \fIdefaultqmode\fR is \fCquote\fR.
.IP
The \fCquote=\fR parameter (optional) names fields that should be quoted, when \fIdefaultqmode\fR is \fCnoquote\fR.
.LP
\fIfields\fR should be a comma-delimited list of fieldnames with no embedded whitespace.
.LP
Here are the \fC#sqlbuild\fR conversion rules.  
Empty fields are converted to \fCnull\fR.
Fields that are to be quoted are enclosed in 
double quotes (\fC"\fR); if any embedded double quotes are found these are converted to single 
quotes (avoids embedded escape characters and
works well with HTML form tags).  
An entry for every \fIdbtable\fR field is generated (except those mentioned
if \fComit=\fR is used) in logical table order.
.LP
Hint: during development don't put the \fC#sqlbuild\fR within a \fC#sql\fR / \fC#endsql\fR right away;
first put it within a \fC<pre>\fR / \fC</pre>\fR and just see the SQL that it builds.




#include space
.ig >>
<a name=functions></a>
.>>
.SH Functions
These functions may be used in conjunction with the \fC#sql\fR command.
Many of the functions take an argument \fCdbc\fR which specifies the database
connection path, an integer between 1 and 4 (if omitted, \fC1\fR is assumed).

#include space2

.LP
\fB$sqlrow( dbc )\fR
.IP
Get the next SQL result row.
Result fields are loaded into variables that use the same names as the SQL result columns.
NULL fields will be converted to "".
Returns 0 on success, 1 if no more result lines, or an error code > 1.
See example 3 below.


#include space
.LP
\fB$sqlrowcount( dbc )\fR
.IP
Return the number of result rows produced by the most recently invoked SQL command.

#include space
.LP
\fB$sqlpushrow( dbc )\fR
.IP
Causes the next call to \fC$sqlrow()\fR to get the same row again.

#include space
.LP
\fB$sqlerror( dbc )\fR
.IP
Returns the completion status of the most recently invoked SQL command.
Zero indicates success; nonzero indicates an error.
.br
Example: \fC#if $sqlerror() != 0 ...\fR

#include space
.LP
\fB$sqltabdef( dbc, table )\fR
.IP
Returns a comma-delimited list of the field names in \fItable\fR.  
This requires its own free db channel (if used on same channel as a retrieval in progress
it will intefere).
Example: 
.nf
\0 #set names = $sqltabdef( people )
\0 #set n_names = $count( "*", @names )
.fi

#include space
.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

#include space
.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
.LP
\fB$sqlwritable()\fR
.IP
Returns 0 if the current process can write to the database.
Returns 1 if writes are prohibited because of config file readonly attribute.
Returns 2 if writes cannot be done because of unix file or directory permissions issues.

#include space
.LP
\fB#mode nullrep\fR
.IP
You can control how database \fCnull\fR fields are represented within scripts.
By default they are represented as zero-length strings.  
Use \fCnbsp\fR to convert NULLs to the HTML non-breaking space character \fC&nbsp;\fR
which is useful for avoiding dead table cells.
.nf
#mode nullrep blank      ""   (the default)
#mode nullrep nbsp       &nbsp;
#mode nullrep null       null
#mode nullrep noconvert  
.fi
Note that #mode is not a function but rather a script operator, and should be invoked
before result rows are fetched.

#include space
.ig >>
<a name=examples></a>
.>>
.SH Examples
In \fC./qexamples\fR are a number of examples that do various things, 
see the README file there.

.LP
\fBExample 1. Invoke a simple SQL command and display the results:\fR
.nf
 \0 <pre>
 \0 #sql #dump select * from classlist
 \0 </pre>
 \0
 \0 #if $sqlrowcount() != 0
 \0  <h3>Nothing found</h3>
 \0 #endif
.fi

.LP
\fBExample 2. Similar to above but display results as HTML table rows:\fR
.nf
 \0 #set SEARCH = "gib"
 \0
 \0 <table cellpadding=2>
 \0 #sql #dumphtml select * from classlist where lastname like "@SEARCH*"
 \0 </table>
 \0
 \0 #if $sqlrowcount() != 0
 \0  <h3>Nothing found</h3>
 \0 #endif
.fi

.LP
\fBExample 3. Process result rows one at a time:\fR
.nf
  \0 #set MINCORR = 0.7
  \0
  \0 #sql
  \0   select * from correlations
  \0   where pearson > @MINCORR
  \0 #endshell
  \0
  \0 <table cellpadding=2>
  \0 #while $sqlrow() == 0 
  \0   <tr><td>@var1</td><td>@var2</td><td>@pearson</td><td>N = @n</td></tr>
  \0 #endloop
  \0 </table>
  \0
  \0 #if $sqlrowcount() < 1 
  \0   <h3>No correlations computed</h3>
  \0 #endif
.fi

.LP
\fBExample 4. Use an SQL command to load some variables:\fR
.nf
  \0 #set ID = 908
  \0 #sql #load select lastname, firstname, email from people where id = @ID
  \0 Name: @lastname, @firstname &nbsp; email: @email <br>
.fi

.LP
\fBExample 5. Issue an SQL INSERT command, without using #sqlbuild:\fR
.nf
  \0 #sql
  \0   insert into people (id, lastname, firstname, email )
  \0   values ( @id, "@lastname", "@firstname", "@email", balancedue )
  \0 #endsql
  \0
  \0 #if $sqlerror() != 0
  \0    <h3>An error occurred!</h3>
  \0 #endif
.fi

.LP
\fBExample 6. Issue an SQL INSERT command, using #sqlbuild to handle quoting, etc.:\fR
.nf
  \0 #sql
  \0     #sqlbuild  insert  people  quote   noquote=id,balancedue
  \0 #endsql

.LP
\fBExample 7. Issue an SQL UPDATE command, using #sqlbuild to handle quoting, etc:\fR
.nf
  \0 #sql
  \0   #sqlbuild  update  people  quote  omit=id  noquote=balancedue
  \0   where id = 908
  \0 #endsql

.LP
\fBExample 8. Nested SQL SELECT commands using channels 1 and 2:\fR
.nf
\0  #sql select caseid from cases order by caseid
\0  #while $sqlrow() = 0
\0     #sql #2 select details from casedetails where caseid = @caseid
\0     #while $sqlrow( 2 ) = 0
\0      ....
\0     #endloop
\0  #endloop
.fi
     
.LP
\fBExample 8.\fR
#set FILE = "forms.html#de_examp"
#set TAG = "A data entry form example"
#include link


#include bottom
