#set TITLE = "Your project config file"
#include top


.SH Your project config file - file locations and working parameters
.LP
Your project config file contains important working parameters for the database.
A default config file is created automatically when you 
#set FILE = "project_setup.html"
#set TAG = "create a SHSQL database."
#include link
The config file should be located in your project directory and named \fCconfig\fR.
.LP
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, \fBdowntime\fR refers to maintenance time when there 
are no live users accessing the system.
.LP
\fBshsql\fR applications need to read the config file before doing anything
else.  They find the config file by checking the
\fBSHSQL_DB\fR environment variable.
.LP
A config file must exist for each \fBshsql\fR 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.

#include space

.SH Project directory structure
The default structure for a project is shown below.  
.nf
			   (projectdir)
				|
      __________________________|_______________________ 
     |	      |	 	|	  |         |		|
   config    data    indexes 	locks      logs		tmp
             | |     | |        | |        |          | | | | 
             o o     o o        o o        o          o o o o 
.fi

#include space

.SH An example config file
A config file is made up of several simple \fCparameter: value\fR pairs.
Lines beginning with \fC//\fR are taken as comments.
Values may include @variables; use \fCvarvalue\fR to set a variable.
Here's an example \fBshsql\fR config file:
.IP
.nf
// this is a shsql config file
projectdir: 	/home/steve/proj1
tmpdir: 	/home/steve/proj1/tmp
dbcommonwordsfile: /home/steve/proj1/commonwords
.fi

#include space

.SH PARAMETERS

#include space2

.ig >>
<a name=projectdir></a>
.>>
.LP
\fBprojectdir:\fR
.IP \0
Path name of directory where database table files reside.
Contains the config file and \fCdata\fR, \fCindexes\fR, \fClocks\fR, and \fClogs\fR subdirectories.
Can be safely changed during downtime 
after you move the actual data directory with all its contents.

#include space

.ig >>
<a name=dbtmptabledir></a>
.>>
.LP
\fBdbtmptabledir:\fR
.IP \0
Path name of directory where database temporary table files reside.
If not specified, \fBtmpdir\fR will be used.
Can be safely changed during downtime if the new directory already exists with correct permissions.

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

.LP
\fBtmpdir:\fR
.IP \0
Directory to be used for working temporary files.
Default is \fC/tmp\fR.
Can be safely changed during downtime if the new directory already exists with correct permissions.


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

.LP
\fBdbbin:\fR
.IP \0
Path name of directory where \fBshsql\fR executables (such as \fCshsql_join\fR and \fCshsql_create\fR)
reside.  This does not need to be specified if the \fBshsql\fR executables are locatable via PATH.
This attribute may be safely changed during downtime, provided the named directory already exists and
contains shsql executables.

#include space

.ig >>
<a name=dbnull></a>
.>>
.LP
\fBdbnull:\fR
.IP \0
Symbol used to represent missing, blank, or zero length values in database files.
Default is equals-sign (\fC=\fR).
May be from one to four characters in length.
Your \fCNULL\fR 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.
.br
Example: \fCdbnull: ~\fR

.ig >>
<a name=delim></a>
.>>
#include space
.LP
\fBdbdelimchar:\fR
.IP \0
Allowable values are \fCspace\fR and \fCtab\fR.  Default is \fCspace\fR.
This attribute defines the field delimitation character that will be used 
when \fBshsql\fR writes data records (INSERT, UPDATE, SELECT INTO, etc.).
When reading, \fBshsql\fR always accepts fields delimited by whitespace (any
mixture of \fCspace\fR and \fCtab\fR).
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.
.br
Example: dbdelimchar: tab

// #include space
// .ig >>
// <a name=dbspacerep></a>
// .>>
// .LP
// \fBdbspacerep:\fR
// .IP
// Defines a character to be used to represent embedded spaces in data files when whitespace 
// delimitation (a \fCdbdelimchar\fR of space or tab) is in effect.  Default is underscore (\fC_\fR).
// 
// .br
// Example: dbspacerep: `

#include space

.ig >>
<a name=dbwildcard></a>
.>>
.LP
\fBdbwildcard:\fR
.IP \0
Character to be used as a general wild card in \fCWHERE\fR clauses.  Default is \fC*\fR.
Standard SQL uses \fC%\fR.
This attribute may be safely changed during downtime, although your existing code may need modification.
.br
Example: \fCdbwildcard: %\fR

#include space
.ig >>
<a name=dbwildcard1></a>
.>>
.LP
\fBdbwildcard1:\fR
.IP \0
Character to be used as a wild card to match any single character in \fCWHERE\fR clauses.  Default is \fC?\fR.
This attribute may be safely changed during downtime, although your existing code may need modification.
.br
Example: \fCdbwildcard: %\fR

#include space
.ig >>
<a name=dbmaxrows_select></a>
.>>
.LP
\fBdbmaxrows_select:\fR
.IP \0
The maximum number of rows to be selected in any one \fCSELECT\fR operation.
Default is 2000.  May be overridden within
query using shsql's \fCMAXROWS\fR keyword.
Queries that find more rows than the limit, will fail.
This attribute may be safely changed at any time.

#include space
.ig >>
<a name=dbmaxrows_update></a>
.>>
.LP
\fBdbmaxrows_update:\fR
.IP \0
The maximum number of rows to be updated in any one \fCUPDATE\fR or \fCDELETE\fR operation.  
Default is 2000.  May be overridden within
query using shsql's \fCMAXROWS\fR keyword.
Queries that find more rows than the limit will fail.
This attribute may be safely changed at any time.

#include space

.ig >>
<a name=dbrecordlock_timeout></a>
.>>
.LP
\fBdbrecordlock_timeout:\fR
.IP \0
The amount of time (in minutes) that it takes for a record lock to automatically expire.
Default is \fC30\fR.
This attribute may be safely changed at any time.

#include space

.ig >>
<a name=dbwritelock_ntries></a>
.>>
.LP
\fBdbwritelock_ntries:\fR
.IP \0
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.

#include space

.ig >>
<a name=dbreadonly></a>
.>>
.LP
\fBdbreadonly:\fR
.IP \0
Default is \fC0\fR.  If set to \fC1\fR, the database will be read-only.
Read-only behavior is as follows: 
All \fCINSERT\fR,
\fCUPDATE\fR, \fCDELETE\fR, \fCCREATE\fR, \fCDROP\fR, \fCALTER\fR, and \fCMAINTAIN\fR operations will be 
prohibited and result in an error.  
\fCSELECT INTO\fR temporary tables is allowed, but
\fCSELECT INTO\fR operations that update ordinary files or regular database tables will be prohibited
and result in an error.
\fCSELECT .. FOR UPDATE\fR is downgraded to just an ordinary non-locking \fCSELECT\fR.
.br
This attribute may be safely changed at any time.

#include space
.ig >>
<a name=dbmustindex></a>
.>>
.LP
\fBdbmustindex:\fR
.IP \0
Default is \fC0\fR.  If set to \fC1\fR, 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:
\fCtable scan prohibited on this table\fR


#include space
.ig >>
<a name=dbcommonwordsfile></a>
.>>
.LP
\fBdbcommonwordsfile:\fR
.IP \0
Full path name of a file that contains very common words such as \fCand\fR and 
\fCthe\fR, one per line.
Used when building 
#set FILE = "indexes.html#indextype"
#set TAG = "word indexes,"
#include link
for better search efficiency.
Common words should be inserted into a file, one word per line.
See the \fCsqlexampledb\fR for an example English common words file.


#include space
.ig >>
<a name=dbindextrunc></a>
.>>
.LP
\fBdbindextrunc:\fR
.IP \0
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.


.ig >>
<a name=dbtranslog></a>
.>>
#include space
.LP
\fBdbtranslog:\fR
.IP \0
Default is \fC1\fR.  If set to \fC0\fR, database
transaction logs are not generated.

.ig >>
<a name=dbtranslog_byuser></a>
.>>
#include space
.LP
\fBdbtranslog_byuser:\fR
.IP \0
Default is \fC0\fR.  If set to \fC1\fR, a
#set FILE = "logs.html"
#set TAG = "separate transaction log file"
#include link
will be maintained for each user, based on
#set FILE = "identity.html"
#set TAG = "IDENTITY."
#include link
The log file will be named \fClogs/dbtranslog.\fIidentity\fR .
This attribute may be safely changed at any time.

#include space

.LP
\fBdbdebugmode:\fR
.IP \0
If set to \fC1\fR, debug mode is turned on and diagnostic info will be written to standard error.
Also may be set to \fC2\fR to show details on index lookups.
This attribute may be safely changed any time.

#include space


.LP
\fBvarvalue:\fR
.IP \0
Preset a variable to a value.  
This may be used to set a variable that will be referenced later
in the config file.  
.br
Example: \fCvarvalue:  DIR=/home/steve/myproj\fR

#include space

.LP
\fBputenv:\fR
.IP \0
Set a shell environment variable for the benefit of subprocesses.
.br
Example: \fCputenv:  SHSQL_DB=@@DIR\fR


#include bottom
