shsql: installing, troubleshooting, support

SQL database system
| Manual page for installing,(troubleshooting,)

## Installing SHSQL

- Download from `shsql.sourceforge.net`.`` Software distribution directory can be located anywhere (user directory or system directory)
- `cd sqlsrc; make`
  gcc is required. There are no library dependencies.`` Any UID can be used to run the build.`` The resulting executables will be put into `./bin`
- Add the shsql bin to your search PATH
  Now you're ready to create a SHSQL database.``

## Typical problems

Creates, joins, etc. not working.

  shsql must be able to invoke its own executables, to do things such as JOIN, CREATE, and MAINTAIN.`` The shsql bin must be in your command PATH, or else `dbbin:` must be defined in your to the full path name of the bin directory where shsql executables reside.`` project config file (If you are doing CGI work, you must define `dbbin`, since CGI programs don't have access to your command PATH).``

Updates always getting the message "update refused"

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

Database read waits indefinitely

  Indicates that a .readlock file has been left in the `./locks` directory by a process. After verifying that it is invalid it may be removed.``

Getting the message: "sql SELECT: 2000 row(s) retrieved, additional row(s) found but ignored (see MAXROWS)"

  shsql starts out with an upper limit of 2000 rows. You can raise this by setting dbmaxrows_select in your project config file or on a query-by-query basis by adding `maxrows = NNNNN` at the end of the query.`` This rule holds true for `UPDATE` and `DELETE` commands (the config attribute is `dbmaxrows_update` for these).``

Join not returning enough rows.

  There may be issues with multiple rows sharing the same join key.`` If so, use one of the other join types.`` More info.``

Slow retrieval from a larger table for which indexes should be in effect.

  Be sure that the where clause is specified correctly so as to activate the index.`` You can use shsql -debug for more insight into how the query is being processed.`` Another possibility is to set dbmustindex in your config file which prohibits table scans on any table for which an index exists.``

Only one row returned with `SELECT .. GROUP BY` when many were expected.

  All fields named in the `GROUP BY` clause must be present in the `SELECT` item list.``

Underscores disappearing from a field that should have them, such as an email address.

  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 SQLMODE command, then turn it back on again afterwards.``

Numeric comparisons such as greater than or less than not working properly.

  Since shsql 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 created using the `ORDER = NUMERIC` attribute.`` If using SELECT .. ORDER BY, the `NUMERIC` order attribute must be specified.``

## Reporting Bugs

Steve Grubb is the original author of shsql.`` Bug reports may be sent to me at `scg@jax.org`.`` If there is sufficient interest I will initiate a yahoo newsgroup for shsql.``

If you're reporting a bug please indicate your shsql version number (type `shsql -ver` 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.``

About the author.``
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` February 16, 2005.