shsql: your project config file

SQL database system
| Manual page for Your(project)

## Your project config file - file locations and working parameters

Your project config file contains important working parameters for the database.`` A default config file is created automatically when you create a SHSQL database.`` The config file should be located in your project directory and named `config`.``

You can modify your config file as desired using a text editor. This should be done with caution on an active database.`` Each parameter description below indicates when the parameter may be safely changed. In those descriptions, downtime refers to maintenance time when there are no live users accessing the system.``

shsql applications need to read the config file before doing anything else. They find the config file by checking the SHSQL_DB environment variable.``

A config file must exist for each shsql database.`` If you have multiple copies of the same database (for example a development node and a production node), each copy must have a config file.``

## Project directory structure

The default structure for a project is shown below.

    			   (projectdir)
    				|
          __________________________|_______________________
         |	      |	 	|	  |         |		|
       config    data    indexes 	locks      logs		tmp
                 | |     | |        | |        |          | | | |
                 o o     o o        o o        o          o o o o

## An example config file

A config file is made up of several simple `parameter: value` pairs.`` Lines beginning with `//` are taken as comments.`` Values may include @variables; use `varvalue` to set a variable.`` Here's an example shsql config file:

      projectdir: 	/home/steve/proj1
      tmpdir: 	/home/steve/proj1/tmp
      dbcommonwordsfile: /home/steve/proj1/commonwords

## PARAMETERS

projectdir:

  Path name of directory where database table files reside.`` Contains the config file and `data`, `indexes`, `locks`, and `logs` subdirectories.`` Can be safely changed during downtime after you move the actual data directory with all its contents.``

dbtmptabledir:

  Path name of directory where database temporary table files reside.`` If not specified, tmpdir will be used.`` Can be safely changed during downtime if the new directory already exists with correct permissions.``

tmpdir:

  Directory to be used for working temporary files.`` Default is `/tmp`.`` Can be safely changed during downtime if the new directory already exists with correct permissions.``

dbbin:

  Path name of directory where shsql executables (such as `shsql_join` and `shsql_create`) reside. This does not need to be specified if the shsql executables are locatable via PATH.`` This attribute may be safely changed during downtime, provided the named directory already exists and contains shsql executables.``

dbnull:

  Symbol used to represent missing, blank, or zero length values in database files.`` Default is equals-sign (`=`).`` May be from one to four characters in length.`` Your `NULL` symbol should not cooincide with something that could occur as a non-null field in your data, and should never be a valid numeric quantity.`` You can change this config parameter during downtime but you must first manually change all existing occurances of the null symbol in existing data files.``
  Example: `dbnull: ~`

dbdelimchar:

  Allowable values are `space` and `tab`. Default is `space`.`` This attribute defines the field delimitation character that will be used when shsql writes data records (INSERT, UPDATE, SELECT INTO, etc.).`` When reading, shsql always accepts fields delimited by whitespace (any mixture of `space` and `tab`).`` You can change this config parameter during downtime but you must first manually change all existing occurances of the delimiter character in existing data files.``
  Example: dbdelimchar: tab

dbwildcard:

  Character to be used as a general wild card in `WHERE` clauses. Default is `*`.`` Standard SQL uses `%`.`` This attribute may be safely changed during downtime, although your existing code may need modification.``
  Example: `dbwildcard: %`

dbwildcard1:

  Character to be used as a wild card to match any single character in `WHERE` clauses. Default is `?`.`` This attribute may be safely changed during downtime, although your existing code may need modification.``
  Example: `dbwildcard: %`

dbmaxrows_select:

  The maximum number of rows to be selected in any one `SELECT` operation.`` Default is 2000. May be overridden within query using shsql's `MAXROWS` keyword.`` Queries that find more rows than the limit, will fail.`` This attribute may be safely changed at any time.``

dbmaxrows_update:

  The maximum number of rows to be updated in any one `UPDATE` or `DELETE` operation. Default is 2000. May be overridden within query using shsql's `MAXROWS` keyword.`` Queries that find more rows than the limit will fail.`` This attribute may be safely changed at any time.``

dbrecordlock_timeout:

  The amount of time (in minutes) that it takes for a record lock to automatically expire.`` Default is `30`.`` This attribute may be safely changed at any time.``

dbwritelock_ntries:

  The number of retries that occur before an attempt to gain a write lock gives up.`` Default is 8.`` Each try corresponds with slightly less than one second.`` This attribute may be safely changed at any time.``

dbreadonly:

  Default is `0`. If set to `1`, the database will be read-only.`` Read-only behavior is as follows: All `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `ALTER`, and `MAINTAIN` operations will be prohibited and result in an error. `SELECT INTO` temporary tables is allowed, but `SELECT INTO` operations that update ordinary files or regular database tables will be prohibited and result in an error.`` `SELECT .. FOR UPDATE` is downgraded to just an ordinary non-locking `SELECT`.``
  This attribute may be safely changed at any time.``

dbmustindex:

  Default is `0`. If set to `1`, table scans are prohibited on any table that has any index associated with it. Any retrieval involving such a table, that is determined to require a table scan, will terminate in the following error: `table scan prohibited on this table`

dbcommonwordsfile:

  Full path name of a file that contains very common words such as `and` and `the`, one per line.`` Used when building word indexes, for better search efficiency.`` Common words should be inserted into a file, one word per line.`` See the `sqlexampledb` for an example English common words file.``

dbindextrunc:

  Default is 15. The number of significant characters in an alphanumeric index entry.`` Index entry tags are truncated at this point. You might want to raise this if you have primary keys more than 15 characters long.``

dbtranslog:

  Default is `1`. If set to `0`, database transaction logs are not generated.``

dbtranslog_byuser:

  Default is `0`. If set to `1`, a separate transaction log file will be maintained for each user, based on IDENTITY.`` The log file will be named `logs/dbtranslog.`identity .`` This attribute may be safely changed at any time.``

dbdebugmode:

  If set to `1`, debug mode is turned on and diagnostic info will be written to standard error.`` Also may be set to `2` to show details on index lookups.`` This attribute may be safely changed any time.``

varvalue:

  Preset a variable to a value. This may be used to set a variable that will be referenced later in the config file.
  Example: `varvalue: DIR=/home/steve/myproj`

putenv:

  Set a shell environment variable for the benefit of subprocesses.``
  Example: `putenv: SHSQL_DB=@DIR`
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` March 19, 2004.