.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: your project config file</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 Your project config file TDH "19-MAR-2004   TDH scg@jax.org" 


.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 
.ig >>
<a href="project_setup.html">
.>>
\0create a SHSQL database.
.ig >>
</a>
.>>
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.

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

.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

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

.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
projectdir: 	/home/steve/proj1
tmpdir: 	/home/steve/proj1/tmp
dbcommonwordsfile: /home/steve/proj1/commonwords
.fi

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

.SH PARAMETERS

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

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

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

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

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


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

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

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


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

.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

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

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

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

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

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

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

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

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

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

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


.ig >>
<br><br><br>
.>>
.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 
.ig >>
<a href="indexes.html#indextype">
.>>
\0word indexes,
.ig >>
</a>
.>>
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.


.ig >>
<br><br><br>
.>>
.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>
.>>
.ig >>
<br><br><br>
.>>
.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>
.>>
.ig >>
<br><br><br>
.>>
.LP
\fBdbtranslog_byuser:\fR
.IP \0
Default is \fC0\fR.  If set to \fC1\fR, a
.ig >>
<a href="logs.html">
.>>
\0separate transaction log file
.ig >>
</a>
.>>
will be maintained for each user, based on
.ig >>
<a href="identity.html">
.>>
\0IDENTITY.
.ig >>
</a>
.>>
The log file will be named \fClogs/dbtranslog.\fIidentity\fR .
This attribute may be safely changed at any time.

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

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

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


.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

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

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


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