.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>shsql: installing, troubleshooting, support</title>
<body bgcolor=99cc99 vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td align=right><a href="shsql_home.html">
<img src="img/shsql.gif" border=0><br><small>SQL database system</a> &nbsp; </td></tr>
<td>
.>>

.TH installing, troubleshooting, support TDH "16-FEB-2005   TDH scg@jax.org" 

.SH Installing SHSQL

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

.ig >>
<br><br>
.>>

.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

.ig >>
<br><br>
.>>

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

.ig >>
<br><br>
.>>
Now you're ready to
.ig >>
<a href="project_setup.html">
.>>
\0create a SHSQL database.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.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 
to the full path name of the bin directory where shsql executables reside.
.ig >>
<a href="config.html#dbbin">
.>>
\0project config file
.ig >>
</a>
.>>
(If you are doing CGI work, you \fBmust\fR define \fCdbbin\fR, since CGI programs
don't have access to your command PATH).

.ig >>
<br><br>
.>>

.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.

.ig >>
<br><br>
.>>
.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.

.ig >>
<br><br>
.>>

.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
.ig >>
<a href="config.html#dbmaxrows_select">
.>>
\0dbmaxrows_select in your project config file
.ig >>
</a>
.>>
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).

.ig >>
<br><br>
.>>
.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.
.ig >>
<a href="join.html">
.>>
\0More info.
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>
.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
.ig >>
<a href="indexes.html">
.>>
\0index.
.ig >>
</a>
.>>
You can use \fBshsql -debug\fR for more insight into how the query is being processed.
Another possibility is to set
.ig >>
<a href="config.html#dbmustindex">
.>>
\0dbmustindex in your config file
.ig >>
</a>
.>>
which prohibits table scans on any table for which an index exists.

.ig >>
<br><br>
.>>
.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.

.ig >>
<br><br>
.>>
.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
.ig >>
<a href="sqlmode.html">
.>>
\0SQLMODE
.ig >>
</a>
.>>
command, then turn it back on again afterwards.


.ig >>
<br><br>
.>>

.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 
.ig >>
<a href="create.html#index">
.>>
\0created
.ig >>
</a>
.>>
using the \fCORDER = NUMERIC\fR attribute.
If using 
.ig >>
<a href="select.html#orderby">
.>>
\0SELECT .. ORDER BY,
.ig >>
</a>
.>>
the \fCNUMERIC\fR order attribute must be specified.

.ig >>
<br><br><br>
.>>

.SH Reporting Bugs

.ig >>
<a href="steve.html">
.>>
\0Steve Grubb
.ig >>
</a>
.>>
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
.ig >>
<a href="http://ploticus.sourceforge.net/steve.html">
.>>
\0About the author.
.ig >>
</a>
.>>


.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="shsql_home.html">
<img src="img/shsql.gif" border=0></a><br>
<a href="Copyright.html">Copyright Steve Grubb</a> &nbsp;
</td></tr>
</table>
.>>

