Jade ( JAva oDbc Engine )
-------------------------

Release 1996.02

What is Jade?
-------------
Jade is a client/server solution for Java programming language to talk 
to Microsoft ODBC server. If you want to use Java to access your ODBC 
data, Jade is the solution for you.

Why Jade?
---------
1. If you know ODBC 2.0 APIs call, you know how to program the Jade 
   API. Jade is direct translation of ODBC APIs. Since the APIs are 
   the same, your will not need to spend a lot of time to learn how 
   to use the program.
2. We give you the source code and you can change it for your own use.

How to order
------------
For personal use, the package costs 45$. 
For commercial use (as a library in your web site), it costs 100$.
To license our source code, it costs 200$ per version. You can modify 
and redistribute our source code WITHOUT extra loyalty for your own product. 

To order,
1. simple fill out this form
    Name:               
    Title:
    Company:
    Address:
    Phone Number:
    Fax Number:
    Email Address:
    [ ] Personal Use....................  USD$45
    [ ] Commercial Use.................. USD$100
    [ ] To license our source code.............. USD$200
2.  send this form and the check to:
    Thomas Kwan
    7479, 18th Ave.,
    Burnaby, Canada
    V3N 1H8
Please make the check payable to: Thomas Kwan
For more information, please send email to: nkkwan@lynx.bc.ca. Or check out our web 
site at: http://www.hktrade.com/clients/kwan

How to contact us
-----------------
For sales information, please send mail to: nkkwan@lynx.bc.ca
For technical issue or bug report, please send mail to: tkwan@aa.net
Our web site location is: http://www.hktrade.com/clients/kwan
Our mailing address is:
    Thomas Kwan
    7479, 18th Ave.,
    Burnaby, Canada
    V3N 1H8

Release 1996.02 Note
--------------------
Beta 1 release for Jade. 

How to install and use Jade
---------------------------
Jade consists of two parts: Jade client Java classes library and Jade 
Microsoft Windows server exe program. 

The installation of Jade is very easy. You just need to run:
        Jade.exe
in your Microsoft Windows NT WWW server. Then the Jade socket server 
will listen to the TCP/IP port 4201 for ODBC request.

Once the Jade socket server is running, you can use your Java program to do 
ODBC request. Here is an example Jade client program.

        // Create a JadeDB object which connect to the machine "moon" to TCP/IP port 4201
        JadeDB db = new JadeDB("moon", 4201);
        if (!db.m_err)
        {
            // variable to remember error state
            OutString state=new OutString("");
            OutLong Error=new OutLong(0);
            OutString ErrorMsg=new OutString("");
            
            // Connect to the database called Expense with the admin username
            if ( db.SQLConnect( "Expense","admin", "" ) == db.SQL_ERROR )
            {
                // if error, print out the error state
                db.SQLError( db.SQL_ERROR_CONNECT, state, Error, ErrorMsg );
                System.err.println( state+" "+Error+" "+ErrorMsg);
            }
            if ( db.SQLExecDirect( "SELECT * FROM Expense_Details" ) == 
            db.SQL_ERROR )
            {
                db.SQLError( db.SQL_ERROR_HSTMT, state, Error, ErrorMsg );
                System.err.println( state+" "+Error+" "+ErrorMsg);
            }
            // start to retrieve data
            OutInteger ExpenseDetailId=new OutInteger(0);
            OutInteger ExpenseReportId=new OutInteger(0);
            OutInteger ExpenseCategoryId=new OutInteger(0);
            OutString ExpenseItemAmount=new OutString("");
            OutString ExpenseItemDescription=new OutString("");
            OutTimestamp ExpenseDate=new OutTimestamp(0,0,0,0,0,0,0);
            
            // reset the result vector
            db.JadeResetBindVector();
            // bind the column
            db.SQLBindCol( 1, db.SQL_C_SLONG, ExpenseDetailId );
            db.SQLBindCol( 2, db.SQL_C_SLONG, ExpenseReportId );
            db.SQLBindCol( 3, db.SQL_C_SLONG, ExpenseCategoryId );
            db.SQLBindCol( 4, db.SQL_C_CHAR, ExpenseItemAmount );
            db.SQLBindCol( 5, db.SQL_C_CHAR, ExpenseItemDescription );
            db.SQLBindCol( 6, db.SQL_C_TIMESTAMP, ExpenseDate );
            
            while (true)
            {
                if ( db.SQLFetch() != db.SQL_SUCCESS )
                    break;

                // get the binded result data from the server to the client
                db.JadeSQLGetValues();
                db.SQLTransact( db.SQL_COMMIT );
                
                System.err.println(ExpenseDetailId);
                System.err.println(ExpenseReportId);
                System.err.println(ExpenseCategoryId);
                System.err.println(ExpenseItemAmount);
                System.err.println(ExpenseItemDescription);
                System.err.println(ExpenseDate);
            }
        }

API Specification
-----------------

Programming Hints
-----------------
JadeDB class provides all the ODBC functions except for:
        RETCODE JadeSQLAllocConnect();
        RETCODE JadeSQLAllocEnv();
        RETCODE JadeSQLAllocStmt();
        RETCODE JadeSQLFreeConnect();
        RETCODE JadeSQLFreeEnv();
        RETCODE JadeSQLFreeStmt();
which is handled by the server. So, the user will need need to worry about
Alloc and Free the memory handle.

Meanwhile, the JadeDB class also provide 3 additions APIs:
        RETCODE JadeSetBindValues();
        RETCODE JadeGetBindValues();
        RETCODE JadeResetBindValues();
JadeSetBindValues is used before you execute a INSERT or UPDATE SQL
query to the ODBC server. It will let the java clients to ship the data
from the client to the server. JadeGetBindValues is used after you
execute a SELECT query and you want to retrieve the binded result to the
clients. Then JadeResetBindValues is used to reset all the binding 
variable before you call SQLBindCol or SQLBindParameter.

Since Java does not allow basic type parameter passing, we create the
OutInteger, OutLong, OutTimestamp, OutDate, OutTime, OutShort class to
help us to pass the parameters. The user should reference to the source
code and examples for correct usage of each class.

Known Problems
--------------


----------------------------------------------------------------------------
Jade is the trade mark of Kwan Software Research.
Java is the trade mark of Sun Micro System.
Microsoft Windows is the trade mark of Microsoft Inc.
