#set TITLE = "database tables"
#include top

.SH Database tables
\fBshsql\fR stores data in tables.
Tables may be created using the 
#set FILE = "create.html#table"
#set TAG = "CREATE TABLE"
#include link
command, and updated using the 
#set FILE = "iud.html"
#set TAG = "INSERT, UPDATE, or DELETE"
#include link
commands.
There are no definition files, etc. that need to be updated when a table is created.
The only information \fBshsql\fR keeps about a table are its field names, and these
reside in the data file field name header.  \fBshsql\fR data fields are typeless.
.LP
This manual page discusses standard database tables.
In addition to these \fBshsql\fR can also store and use data in 
#set FILE = "temptables.html"
#set TAG = "temporary tables"
#include link
and
#set FILE = "ordfiles.html"
#set TAG = "ordinary files.
#include link
Also, \fBshsql\fR allows database tables to be organized 
#set FILE = "hier.html"
#set TAG = "hierarchically."
#include link
See also the
#set FILE = "tabletypes.html"
#set TAG = "shsql table types chart"
#include link
where these table types are compared.

#include space
.SH Security concerns
Because shsql allows 
#set FILE = "ordfiles.html"
#set TAG = "any readable file on your file system"
#include link
to be accessed, avoid situations where table names are built
using user-supplied values (such as CGI user variables).. this might
allow a hacker to see arbitrary files.

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

.SH Fields 
\fBshsql\fR tables contain one or more fields (sometimes called columns in 
relational parlance).  Fields are specified in the \fCCREATE TABLE\fR command.
To see the names of all fields in a table, the 
#set FILE = "tabdef.1.html"
#set TAG = "tabdef(1)"
#include link
command may be used.  The SQL
#set FILE = "alter.html"
#set TAG = "ALTER TABLE"
#include link
command can be used to add or remove fields after a table has been created.


#include space

.SH Naming
Table names and field (column) names are case sensitive, max length 30 characters, 
may not contain any white space or punctuation character other than underscore (_), 
and must begin with an alphabetic character.

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

.SH Data types
\fBshsql\fR uses no data types.  All fields are considered alphanumeric.
Fields that need to be handled numerically require that the keyword NUMERIC be given 
in an ORDER BY or CREATE INDEX command.
Dates (etc.) may be stored directly if using notation that sorts naturally (such as YYYY/MM/DD)
, otherwise dates must be converted to a numeric equivalent (such as Julian) before 
reaching \fBshsql\fR.

#include space
.SH Importing data into a shsql table
Because it uses simple \fCASCII\fR files, \fBshsql\fR 
has no formal "import" or "bulk load" facility.  
If you have a file that is to become a \fBshsql\fR table, be sure it conforms to the 
#set FILE = "#structure"
#set TAG = "table structure specification,"
#include link
including a field name header.
#set FILE = "create.html#table"
#set TAG = "CREATE TABLE"
#include link
should not be used in this case.

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

.SH Table file structure 
Database tables are stored as plain \fCASCII\fR text files.
These files are located in the database \fCdata\fR directory.
Table files conform to these specifications:

.IP \(bu
\fCASCII\fR text, one record per line, each record terminated by a newline character.

.IP \(bu
Any line beginning with \fC//\fR is taken as a comment and skipped.

.IP \(bu
Within a record are one or more fields.  Fields are whitespace-delimited.
Whitespace means any combination of one or more spaces or tabs.
Records that \fBshsql\fR writes (INSERT, UPDATE, SELECT INTO, etc) have space-delimited
fields by default.  If you want to maintain tab-delimited data files, 
#set FILE = "config.html#delim"
#set TAG = "dbdelimchar"
#include link
should be set to \fCtab\fR in your config file.

.IP \(bu
The first non-comment line in the file must contain the field names, each separated by whitespace.

.IP \(bu
Embedded whitespace characters are represented in the data file using underscore  
characters.  \fBshsql\fR performs the conversion transparently.

.IP \(bu
Additional whitespace characters may be located at the end of a record for padding
(so that future updates can use the same space even if a little bigger).

.IP \(bu
Some lines may contain nothing but whitespace characters.  \fBshsql\fR does this
to erase records that have been deleted or moved.

.IP \(bu
Individual fields cannot be longer than 255 characters; lines cannot be longer than 3000 
characters; maximum of 80 fields per table.  These limits are defined in \fCshsql.h\fR.

.LP
You can create a database table manually simply by creating a file
that conforms to these specifications; you don't have to do a \fCCREATE TABLE\fR.

#include space
.ig >>
<a name=edit></a>
.>>
.SH Manually editing data table files
.LP
\fBshsql\fR data tables can be edited manually by the database owner using the
#set FILE = "dataedit.1.html"
#set TAG = "dataedit(1)"
#include link
utility.  
.LP
\fBWarning!\fR Never edit data files directly in an active database without using 
#set FILE = "dataedit.1.html"
#set TAG = "dataedit(1)"
#include link
or some other process that interfaces with \fBshsql\fR's file locking scheme.
Other processes won't know the table is being modified and corrupted data could result.
.LP
\fBWarning!\fR Care should be exercised during manual editing.  Valid
#set FILE = "#structure"
#set TAG = "table structure"
#include link
must be maintained.
.LP
dataedit(1) manages the file locking, then invokes your favorite
text editor based on the \fCEDITOR\fR environment variable.  When you're
done editing, it will check for any indexes associated with the table,
since these will likely need to be rebuilt.

#include space
.SH Manually creating data table files
Tables can be created manually instead of using SQL
\fCCREATE TABLE\fR.  In your database \fCdata\fR directory,
create a file using the same name that you want for your table.
The first line in the file should contain all of the field names, separated
by a space (or whatever your delimiter character is).  This line should
terminate with a newline.  This will be the field name header for the table.
Save and you're done.  Locking shouldn't be an issue because presumably there
is no code trying to access the new table yet.

#include space
.SH Reading table files by other programs
Data files can generally be accessed at any time for reading by any desired program.
You may want your program to check to be sure the file isn't
#set FILE = "tablelocking.html#readlock"
#set TAG = "read-locked" 
#include link
before reading.


#include space

.SH Updating table files by other programs
\fBshsql\fR data tables can be created or updated by other programs.  Use the
#set FILE = "dataedit.1.html"
#set TAG = "dataedit(1)"
#include link
utility to invoke the command.  
It will automatically handle locking and rebuilding of any indexes.  Valid
#set FILE = "#structure"
#set TAG = "table structure"
#include link
must be maintained.
See also the 
#set FILE = "#edit"
#set TAG = "warnings in the Manual Editing section" 
#include link
above.

#include space

#include bottom
