.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: c language api</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 C language API TDH "13-APR-2004   TDH scg@jax.org" 


.SH C language API
\fBshsql\fR can be accessed via this C language API.  Applications should 
link to \fClibshsql.a\fR.  There are no header files required.
In order to successfully access the database, applications must conform to the 
requirements of the
.ig >>
<a href="environment.html">
.>>
\0shsql environment.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>
.SH Considerations
\fBshsql\fR's idiosynchrasies as described elsewhere in this manual apply to data
retrieved via the API:
.IP \(bu
Retrieved \fCNULL\fR fields will contain the data file \fCNULL\fR symbol as defined in your 
.ig >>
<a href="config.html#dbnull">
.>>
\0project config file
.ig >>
</a>
.>>
(by default this is \fC=\fR).
.IP \(bu
Any embedded underscores present in retrieved fields will have been converted to spaces, and it
will be the responsibility of the application to convert spaces to underscores as
appropriate.


.ig >>
<br><br><br>
.>>
.SH Function library
.LP
Most of these functions take an argument called \fBdbc\fR which is an integer selector 
that allows multiple channels of concurrent SQL access.  Normally \fB0\fR is used, but if 
a retrieval on channel \fB0\fR is currently in progress, a channel of \fB1\fR or higher 
value may be used.  Up to \fB4\fR channels may be active simultaneously (shsql.h MAXCONNECTS).
.LP
All functions are of type \fCint\fR.  See \fBsimple.c\fR in the source code directory
which demonstrates the use of this API.  There is no concept of \fCconnect\fR or \fCdisconnect\fR.

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

.LP
\fC SHSQL_allconfig() \fR
.IP
Read project config file and initialize.
This function must be called before any other.
Function returns 0 if OK, or a non-zero error code.

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

.LP
\fC SHSQL_sql( int dbc, char *sql ) \fR
.IP
Submit an SQL command.  \fCdbc\fR is the channel selector.  
\fCsql\fR is an SQL command.  
For SELECT commands, subsequent call(s) to \fCSHSQL_getrow()\fR will
be required to fetch the results.
Function returns 0 if the SQL command was processed normally, or an
.ig >>
<a href="errorcodes.html">
.>>
\0error code.
.ig >>
</a>
.>>

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

.LP
\fC SHSQL_getrow( int dbc, char *fields[], int *n ) \fR
.IP
Get one row of results from the most recently submitted SELECT command 
on channel \fCdbc\fR.  
Each \fCfields\fR pointer will be set to reference one result field;
there should be enough array members to accomodate your retrievals (80 recommended).
The pointers reference memory that will be available until the next
SQL command is submitted on the channel.
All result fields are represented as character strings, including \fCNULL\fR which will be indicated
using the internal null symbol (equals-sign (=) by default).
\fCn\fR will be set to the number of fields in the result.
Function returns 0 if a row was fetched, 1 if there are no more rows, or an 
.ig >>
<a href="errorcodes.html">
.>>
\0error code.
.ig >>
</a>
.>>

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

.LP
\fC SHSQL_pushrow( int dbc )\fR
.IP
Causes the next call to \fCSHSQL_getrow()\fR to get the same row again.

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

.LP
\fC SHSQL_getnames( int dbc, char *fields[], int *n ) \fR
.IP
Get the names of the result fields from the most recently submitted SELECT
command on channel \fCdbc\fR.  
Each \fCfields\fR pointer will be set to reference one result field name;
there should be enough array members to accomodate your retrievals (shsql.h MAXITEMS)
The pointers reference memory that will be available until the next
SQL command is submitted on the channel.
\fCn\fR will be set to the number of fields in the result.
Function returns 0 if OK, or a non-zero error code.

.LP
\fC SHSQL_tabdef( char *table, char *fields[], int *n ) \fR
.IP
Get the names of fields in \fItable\fR. 


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

.LP
\fC SHSQL_getnrows( int dbc ) \fR
.IP
Return the number of rows retrieved (or inserted, updated, or deleted) by 
the most recently submitted SQL command on channel \fCdbc\fR.
For SELECT commands, the row count will be exact after all rows are fetched
via \fCSHSQL_getrow()\fR but it may not be exact before this time because of
late processing related to DISTINCT, GROUP BY, or LIMIT.  However,
it is always true that a count of zero indicates no rows found and a count
greater than zero indicates at least one row found.
The row count associated with a SELECT INTO is always exact.

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

.LP
\fC SHSQL_writable() \fR
.IP
Returns 0 if the current process can write to the database directory.
Returns 1 if \fCreadonly\fR is set in the config file.
Returns 2 if writing is prevented by unix file or directory permissions.

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

.SH Convenience routines

.LP
\fC SHSQL_getitem( char *sql, char *result ) \fR
.IP
Get a single item from the database on channel 0.  
\fCsql\fR is an SQL SELECT command that retrieves one field, and the result field 
will be copied into \fCresult\fR.  
Function returns 0 on success, or a non-zero error code.

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

.LP
\fC SHSQL_getitems( char *sql, char *fields[] ) \fR
.IP
Get multiple items from the database on channel 0.
\fCsql\fR is an SQL SELECT command that retrieves one or more fields.
\fCfields\fR is an array of character pointers which will be set to reference
the result fields in memory that will continue to be available until the next
SQL command is submitted on channel 0.
Function returns 0 on success, or a non-zero error code.



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

