.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: database tables</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 database tables TDH "02-JUN-2005   TDH scg@jax.org" 

.SH Database tables
\fBshsql\fR stores data in tables.
Tables may be created using the 
.ig >>
<a href="create.html#table">
.>>
\0CREATE TABLE
.ig >>
</a>
.>>
command, and updated using the 
.ig >>
<a href="iud.html">
.>>
\0INSERT, UPDATE, or DELETE
.ig >>
</a>
.>>
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 
.ig >>
<a href="temptables.html">
.>>
\0temporary tables
.ig >>
</a>
.>>
and
.ig >>
<a href="ordfiles.html">
.>>
\0ordinary files.
.ig >>
</a>
.>>
Also, \fBshsql\fR allows database tables to be organized 
.ig >>
<a href="hier.html">
.>>
\0hierarchically.
.ig >>
</a>
.>>
See also the
.ig >>
<a href="tabletypes.html">
.>>
\0shsql table types chart
.ig >>
</a>
.>>
where these table types are compared.

.ig >>
<br><br><br>
.>>
.SH Security concerns
Because shsql allows 
.ig >>
<a href="ordfiles.html">
.>>
\0any readable file on your file system
.ig >>
</a>
.>>
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.

.ig >>
<br><br><br>
.>>
.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 
.ig >>
<a href="tabdef.1.html">
.>>
\0tabdef(1)
.ig >>
</a>
.>>
command may be used.  The SQL
.ig >>
<a href="alter.html">
.>>
\0ALTER TABLE
.ig >>
</a>
.>>
command can be used to add or remove fields after a table has been created.


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

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

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

.ig >>
<br><br><br>
.>>
.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 
.ig >>
<a href="#structure">
.>>
\0table structure specification,
.ig >>
</a>
.>>
including a field name header.
.ig >>
<a href="create.html#table">
.>>
\0CREATE TABLE
.ig >>
</a>
.>>
should not be used in this case.

.ig >>
<br><br><br>
.>>
.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, 
.ig >>
<a href="config.html#delim">
.>>
\0dbdelimchar
.ig >>
</a>
.>>
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.

.ig >>
<br><br><br>
.>>
.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
.ig >>
<a href="dataedit.1.html">
.>>
\0dataedit(1)
.ig >>
</a>
.>>
utility.  
.LP
\fBWarning!\fR Never edit data files directly in an active database without using 
.ig >>
<a href="dataedit.1.html">
.>>
\0dataedit(1)
.ig >>
</a>
.>>
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
.ig >>
<a href="#structure">
.>>
\0table structure
.ig >>
</a>
.>>
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.

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

.ig >>
<br><br><br>
.>>
.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
.ig >>
<a href="tablelocking.html#readlock">
.>>
\0read-locked
.ig >>
</a>
.>>
before reading.


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

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

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

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