.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
-->
</STYLE>
<title>shsql: misc commands</title>
<body bgcolor=99cc99 vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td align=right><a href="Contents.html">
<img src="img/shsql.gif" border=0><br><small>minimalist SQL database</a> &nbsp; </td></tr>
<td>
.>>

.TH misc commands TDH "08-OCT-2002   TDH scg@jax.org" 

.SH Misc commands
This page describes additional \fBshsql\fR commands that can be submitted as SQL
commands.  They are not standard SQL but rather extensions unique to \fBshsql\fR.

.ig >>
<br><br><br>
.>>
.ig >>
<a name=identity></a>
.>>

.SH IDENTITY
\fCIDENTITY\fR allows a user identity to be supplied.
Since \fBshsql\fR doesn't use logins or passwords, this command provides a way of 
identifying a user or session.  An identity must be supplied if the process is going to attempt
to update a table where
.ig >>
<a href="recordlocking.html">
.>>
\0record locking
.ig >>
</a>
.>>
is used.  \fCIDENTITY\fR is also useful in labelling 
.ig >>
<a href="logs.html">
.>>
\0database transaction log and error log entries.
.ig >>
</a>
.>>
Otherwise it is not required.
\fCIDENTITY\fR should be submitted before any SQL commands that update the database.
Typically \fCIDENTITY\fR is set by the middleware which manages user authentication. 
For CGI-based applications, REMOTE_HOST makes a useful identity.
Identity is in effect during the current process only.
.LP
Usage: \fCIDENTITY  \fItag\fR
.LP
Example: \fCidentity  "steve"\fR
.LP
\fItag\fR can be any short identifier.

.ig >>
<br><br><br>
.>>
.ig >>
<a name=pipedef></a>
.>>

.SH PIPEDEF
\fCPIPEDEF\fR allows a shell command to be encapsulated as a "virtual table."
This virtual table can be referenced just like a temporary table in
subsequent \fCSELECT\fR commands.  The syntax is:
.LP
\fCPIPEDEF \fItemptablename\fC   FORMAT  \fIformatname\fC  COMMAND  \fIshellcommand\fR
.LP
\fItemptable\fR names the 
.ig >>
<a href="temptables.html">
.>>
\0temporary table
.ig >>
</a>
.>>
that will be created.  
\fIformatname\fR is the name of an existing
database table or
.ig >>
<a href="tables.html#fdf">
.>>
\0field format definition
.ig >>
</a>
.>>
, or else the special symbol \fC#USEHEADER\fR, which indicates that the data stream
will have a valid field name header like that required for
.ig >>
<a href="ordfiles.html">
.>>
\0ordinary files.
.ig >>
</a>
.>>
.LP
\fIshellcommand\fR is the shell command to be executed.  It will be executed
with the project data directory as its current working directory, at the time
it is accessed in a \fCSELECT\fR command.
The \fIshellcommand\fR must produce a data stream that conforms to \fBshsql\fR's
file format requirements, as required for
.ig >>
<a href="ordfiles.html">
.>>
\0ordinary files.
.ig >>
</a>
.>>
.LP
Security warning: Any user-supplied values should be pre-processed to remove all
characters that have special meaning to the shell, otherwise users
may be able to execute arbitrary commands.
.LP
\fBExample:\fR
\fCpipedef $tmp1 format #useheader command compstats 65 gbvol M\fR


.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="Contents.html">
<img src="img/shsql.gif" border=0></a><br>
<a href="Copyright.html">Copyright Steve Grubb</a> &nbsp;
</td></tr>
</table>
.>>
