#set TITLE = "installing, troubleshooting, support"
#include top

.SH Installing SHSQL

.IP \(bu
Download from \fCshsql.sourceforge.net\fR.
Software distribution directory can be located anywhere (user directory or system directory)

#include space2

.IP \(bu
\fCcd sqlsrc; make\fR
.br
\fBgcc\fR is required.  
There are no library dependencies.
Any UID can be used to run the build.
The resulting executables will be put into \fC./bin\fR

#include space2

.IP \(bu
Add the shsql bin to your search \fBPATH\fR

#include space2
Now you're ready to
#set FILE = "project_setup.html"
#set TAG = "create a SHSQL database."
#include link

#include space

.SH Typical problems

.LP
\fBCreates, joins, etc. not working.\fR
.IP
\fBshsql\fR must be able to invoke its own executables, to do things such as
JOIN, CREATE, and MAINTAIN.
The \fBshsql\fR bin must be in your command PATH, or else
\fCdbbin:\fR must be defined in your 
#set FILE = "config.html#dbbin"
#set TAG = "project config file"
to the full path name of the bin directory where shsql executables reside.
#include link
(If you are doing CGI work, you \fBmust\fR define \fCdbbin\fR, since CGI programs
don't have access to your command PATH).

#include space2

.LP
\fBUpdates always getting the message "update refused"\fR
.IP
The process attempting the update probably isn't owned by the same UID that owns the database,
or is having some other problem gaining access to the data file or lock file.

#include space2
.LP
\fBDatabase read waits indefinitely\fR
.IP
Indicates that a .readlock file has been left in the \fC./locks\fR directory
by a process.  After verifying that it is invalid it may be removed.

#include space2

.LP
\fBGetting the message: "sql SELECT: 2000 row(s) retrieved, additional row(s) found but ignored (see MAXROWS)"\fR
.IP
\fBshsql\fR starts out with an upper limit of 2000 rows.  You can raise this by setting
#set FILE = "config.html#dbmaxrows_select"
#set TAG = "dbmaxrows_select in your project config file"
#include link
or on a query-by-query basis by adding \fCmaxrows = NNNNN\fR at the end of the query.
This rule holds true for \fCUPDATE\fR and \fCDELETE\fR commands (the config attribute
is \fCdbmaxrows_update\fR for these).

#include space2
.LP
\fBJoin not returning enough rows.\fR
.IP
There may be issues with multiple rows sharing the same join key.
If so, use one of the other join types.
#set FILE = "join.html"
#set TAG = "More info."
#include link

#include space2
.LP
\fBSlow retrieval from a larger table for which indexes should be in effect.\fR
.IP
Be sure that the where clause is specified correctly so as to activate the
#set FILE = "indexes.html"
#set TAG = "index."
#include link
You can use \fBshsql -debug\fR for more insight into how the query is being processed.
Another possibility is to set
#set FILE = "config.html#dbmustindex"
#set TAG = "dbmustindex in your config file"
#include link
which prohibits table scans on any table for which an index exists.

#include space2
.LP
\fBOnly one row returned with \fCSELECT .. GROUP BY\fR when many were expected.\fR
.IP
All fields named in the \fCGROUP BY\fR clause must be present in the \fCSELECT\fR
item list.

#include space2
.LP
\fBUnderscores disappearing from a field that should have them, such as an email address.\fR
.IP
Embedded whitespace characters are represented in the data file using underscores.
Then, underscores are converted back to spaces for presentation.
One option is to have your middleware put the underscores back in to fields if spaces
aren't allowed but underscore is (such as an email address).  Another option is to turn off
underscore conversion for a retrieval using the
#set FILE = "sqlmode.html"
#set TAG = "SQLMODE"
#include link
command, then turn it back on again afterwards.


#include space2

.LP
\fBNumeric comparisons such as greater than or less than not working properly.\fR
.IP
Since \fBshsql\fR has no datatypes, the fact that a certain field is to be
processed using numerical comparisons/ordering must be specified explicitly.
An index on this field must be 
#set FILE = "create.html#index"
#set TAG = "created"
#include link
using the \fCORDER = NUMERIC\fR attribute.
If using 
#set FILE = "select.html#orderby"
#set TAG = "SELECT .. ORDER BY,"
#include link
the \fCNUMERIC\fR order attribute must be specified.

#include space

.SH Reporting Bugs

#set FILE = "steve.html"
#set TAG = "Steve Grubb" 
#include link
is the original author of \fBshsql\fR.
Bug reports may be sent to me at \fCscg@jax.org\fR.
If there is sufficient interest I will initiate a yahoo newsgroup for \fBshsql\fR.
.LP
If you're reporting a bug please indicate your \fBshsql\fR version number (type \fCshsql -ver\fR
to find out) and your OS platform.
Please just describe the problem first.  
I may then request that you send me a database directory that reproduces the problem.
.LP
#set FILE = "http://ploticus.sourceforge.net/steve.html"
#set TAG = "About the author."
#include link


#include bottom

