We have developed some DB-Library functions which provide a Sybase interface
for CLIPS.  Our CLIPS programs need to do the following:

        o Open/close a connection to a SQL server
        o Execute commands/queries on the SQL server
        o Assert data returned from the server into CLIPS
        o Trap server errors and display messages to the user

Our strategy was to keep the interface design as simple as possible.  While
it provides a great deal of flexibility, it does leave the responsibility
of constructing the SQL code entirely up to the calling (CLIPS) program.
Also, it is limited to one open SQL server connection at a time.  However,
it provides full insert/delete/update access to the Sybase database and 
allows the results of SQL queries to be asserted into the CLIPS fact-base.

The interface consists of a small number of application-independent "C"
functions, which are built as extensions to CLIPS.  When they encounter an
error, error and message handler functions for the DB-Library routines
display helpful messages describing why the error occurred.  The function
value returned to the caller allows the CLIPS application program to test
for (and handle) the errors.

We have also implemented a utility which creates deftemplate declarations
from information stored in the Sybase system tables.

VERSION INFORMATION:
    CLIPS V6.01
    Sybase SQL Server 4.9.1
    DB-Library 4.6
    SunOS Release 4.1

RELATED FILES:
    dbfun.c                 Source code for the extensions and error/message
                            handlers

    main.c                  In UserFunctions(), describes the functions to
                            CLIPS in main(), initializes DB-Library

    co_clips_makefile       Makes CLIPS commandline interface, with extensions

    create_deftemplate.sh   Utility (implemented as a Bourne shell script)
                            which creates CLIPS deftemplate definitions

    Note:  Examples shown below use the "pubs" database, which is provided by
           Sybase for tutorial purposes.

UTILITIES:

1.  create_deftemplates.sh
    
    Invoke from UNIX command line as follows:  create_deftemplates.sh

    This Bourne shell script creates a text file named "outfile," which
    contains CLIPS deftemplates for the tables specified in variables inside
    the shell script.  Thus the script MUST be customized by the CLIPS
    programmer in order to create the correct deftemplates.

    The purpose of this utility is to save work for the CLIPS programmer who
    wishes to use many tables from within his program.  Rather than typing
    the names and data types of ALL the columns in ALL the tables he wishes
    to use, he changes a few lines of the script and creates the deftemplates
    easily.  For example, if the programmer editted create_deftemplates.sh
    so that the titleauthor table was listed, outfile would contain:

    (deftemplate titleauthor
       (field  au_id                                         
         (type STRING) ) 
       (field  title_id                                      
         (type STRING) ) 
       (field  au_ord                                        
         (type INTEGER) ) 
       (field  royaltyper                                    
         (type INTEGER) ) 
    )

    This file could then be included in any CLIPS application program which
    needed access to the titleauthor table in the pubs database.

CLIPS EXTENSIONS:

1.  dbopen
    Syntax:   (dbopen login password db_name)
    Example:
              CLIPS> (load outfile)
              Defining deftemplate: titleauthor
              CLIPS> (dbopen myloginname mypassword pubs)
              TRUE
              CLIPS>

    This function attempts to connect to the default SQL server, using the
    login name and password specified.  If the connection is successfully
    established, the specified database will be opened.  If there is a
    connection open already, dbopen will close it first. If the login attempt
    fails, an error message is printed and dbopen returns FALSE.  Otherwise,
    dbopen returns TRUE.

2.  dbclose
    Syntax:   (dbclose)
    Example:
              CLIPS> (dbclose)
              TRUE
              CLIPS>

    If the SQL server connection is open, dbclose closes it.  This function
    isn't really needed, since 1) any open connection is closed automatically
    upon exiting CLIPS, and 2) dbopen first closes any open connection.  This
    function always returns TRUE.

3.  dbcmd
    Syntax:   (dbcmd str)
    Example:  
              CLIPS> (dbcmd "select * into #tmp from titleauthor")
              0
              CLIPS> (dbcmd "select * from #tmp")
              25
              CLIPS> (facts)
              CLIPS>

    This function sends the string str to the SQL server for execution.  If
    there are multiple commands in the string, they are all executed.  This
    function returns the number of rows affected by the command, which, if
    no errors occur, is either zero or a positive integer.  If an error is
    encountered, an error message is printed and -1 is returned.

4.  dbquery
    Syntax:   (dbquery str fact_name)
    Example:  
              CLIPS> (facts)
              CLIPS> (dbquery "select * from titleauthor where royaltyper < 30"
                      titleauthor)
              2
              CLIPS> (facts)
              f-0     (titleauthor (au_id "724-80-9391") (title_id "PS1372")
                      (au_ord 2) (royaltyper 25))
              f-1     (titleauthor (au_id "899-46-2035") (title_id "MC3021")
                      (au_ord 2) (royaltyper 25))
              For a total of 2 facts.
              CLIPS>

    This function is similar to dbcmd, except that each row returned is
    asserted as a separate, new CLIPS fact.  The fact is constructed as
    follows:  the name of the fact is fact_name; fields in the fact
    correspond to columns returned from the query.  The fact is first
    constructed and then created by calling AssertString().

    It is assumed that there is a deftemplate declaration for a fact
    named fact_name.  These declarations can be easily created using the
    create_deftemplate.sh utility.
    
5.  dbadd
    Syntax:   (dbadd str)
    Example:  
              CLIPS> (dbadd "select * from titleauthor")
              TRUE
              CLIPS> (dbadd " where royaltyper")
              TRUE
              CLIPS> (dbcmd " < 30")
              2
              CLIPS>

    Concatenates its character string argument onto the DBPROCESS's command
    buffer.  No whitespace is added between character strings, so the user
    must include them within the string.  This function allows the CLIPS
    programmer to construct queries spanning multiple lines of the source
    file, making the CLIPS code much more readable.
