IngTcl 0.8 - An Ingres driver for Tcl
                      =====================================

1. Licensing and copyright
2. What is IngTcl
3. Installation under Windows
4. Installation under UNIX/Linux
5. Tested platforms
6. List of commands
7. Examples


1. Licensing and copyright
==========================

See the file "license.terms" for information on usage and redistribution
of this file, and for a DISCLAIMER OF ALL WARRANTIES.                   
                                                                       
Copyright (c) 2012, 2013 Tomasz Konojacki

Note that I'm not copyright holder for some files in this distribution, for
more information see copyright notices in each file.


2. What is IngTcl
=================

IngTcl is Tcl extension which allows connecting to Actian Ingres database or
Actian Vectorwise from Tcl scripts. It is written using Tcl C API and ESQL/C.

IngTcl is very easy to use, see "Examples" section.


3. Installation under Windows
=============================

To build and install IngTcl under Windows you need following software:

- Ingres
- Tcl (ActiveTcl is recommended)
- Visual C++

Note that if II_SYSTEM environment variable is not set, build process will
fail.

Installation instructions:

1. Extract IngTcl zip archive.
2. Open Visual Studio command prompt.
3. Change current directory to directory which contains extracted files (use 
   "cd" command):

   +---------------------------------------------------------------------------+
   | cd C:\users\xenu\desktop\IngTcl                                           |
   +---------------------------------------------------------------------------+

4. Change directory to "win":

   +---------------------------------------------------------------------------+
   | cd win                                                                    |
   +---------------------------------------------------------------------------+

5. Execute Makefile:

   - TCLDIR should be set to path where Tcl is installed (usually "C:\Tcl")
   - INSTALLDIR usually should be set to (TCLDIR)\lib, for example:
     "C:\Tcl\lib"
   - MACHINE should be set to your architecture - "AMD64" for 64-bit systems and
     "IX86" for 32-bit.

   (Note that this command MUST be entered in SINGLE line)
   +---------------------------------------------------------------------------+
   | nmake /f Makefile.vc TCLDIR=C:\Tcl INSTALLDIR=C:\Tcl\lib MACHINE=IX86     |
   +---------------------------------------------------------------------------+

6. Install:

    (Note that this command MUST be entered in SINGLE line)
   +---------------------------------------------------------------------------+
   | nmake /f Makefile.vc install TCLDIR=C:\Tcl INSTALLDIR=C:\Tcl\lib          |
   | MACHINE=IX86                                                              |
   +---------------------------------------------------------------------------+

7. Done! IngTcl is installed!


4. Installation under UNIX/Linux
================================

To build and install IngTcl under UNIX/Linux you need following software:

- Ingres
- Tcl (on some Linux distributions you need tcl-dev or tcl-devel package)
- C Compiler
- Make

Note that if II_SYSTEM environment variable is not set, build process will
fail.

Installation instructions:

1. Extract IngTcl zip archive.
2. Open terminal emulator.
3. Change current directory to directory which contains extracted files (use 
   "cd" command):

   +---------------------------------------------------------------------------+
   | cd /home/xenu/IngTcl                                                      |
   +---------------------------------------------------------------------------+

4. Run configure:

   +---------------------------------------------------------------------------+
   | ./configure                                                               |
   +---------------------------------------------------------------------------+

5. Execute Makefile:

   +---------------------------------------------------------------------------+
   | make                                                                      |
   +---------------------------------------------------------------------------+

6. Install:

   +---------------------------------------------------------------------------+
   | make install                                                              |
   +---------------------------------------------------------------------------+

7. Done! IngTcl is installed!


5. Tested platforms
===================

IngTcl was tested under following platforms:

- Vectorwise 2.5.1 Enterprise Build 162 + Windows + Visual C++ on x64
- Ingres 10.1 Community Build 125 + Windows + Visual C++ on x64
- Ingres 10.1 Community Build 125 + Linux + gcc on x64
- Ingres 10.1 Community Build 121 + Windows + Visual C++ on x64
- Ingres 10.1 Community Build 121 + Windows + Visual C++ on x86
- Ingres 10.1 Community Build 121 + Linux + gcc on x64
- Ingres 10.1 Community Build 121 + Linux + gcc on x86
- Ingres 9.2.3 Enterprise Build 101 + Windows + Visual C++ on x86

Please report successes and failures to [email protected]

6. List of commands
===================

- ::IngTcl::connect dbname ?login? ?password? ?options?
  
    ::IngTcl::connect to database specified in "dbname" argument.
    
    It returns number of session which is required by other commands, on
    failure it will throw exception.

- ::IngTcl::prepare session statement
  
    ::IngTcl::prepare prepares statement. It should be used only for SELECT
    statements, ::IngTcl::do will be faster for statements which doesn't return
    anything.
    
    This command returns cursor which will be needed for ::IngTcl::execute, on
    failure it will throw exception.


- ::IngTcl::execute session cursor ?arg1 arg2 ...?
    
    It executes statement prepared by ::IngTcl::prepare. arg1, args2 etc. will
    be inserted in place of question marks (?) in statement.

    It returns 1 on success, otherwise it throws an exception.

- ::IngTcl::fetch_row session cursor

    It fetches row from table using specified cursor. When there are no more
    rows, cursor is automatically closed.

    On success, it returns list containg fetched row, otherwise it throws
    an exception.

- ::IngTcl::fetch_column_names session cursor

    It fetches column names from table using specified cursor.

    On success, it returns list containg fetched colum names, otherwise it
    throws an exception.

- ::IngTcl::do session statement

    This command executes statement specified in statement argument. Note that
    there is no way to capture output of statement.

    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::set_autocommit session enable_autocommit

    ::IngTcl::set_autocommit enables or disables AutoCommit for specified session.

    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::set_treat_empty_as_null session cursor treat_empty_as_null

    It enables or disables treatment of empty input values as NULLs. It will
    work only for specified cursor.

- ::IngTcl::commit session

    It commits current transaction.
    
    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::rollback session

    It rollbacks current transaction.
    
    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::close_cursor session cursor
    
    It closes cursor. Note that ::IngTcl::fetch_row automatically closes cursor
    when all rows are fetched.

    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::is_cursor_closed session cursor

    This command returns 1 if specified cursor is closed, otherwise it returns
    0.

- ::IngTcl::delete_cursor session cursor

    ::IngTcl::delete_cursor deletes cursor. You really should delete cursor when
    you don't need it anymore. ::IngTcl::delete_cursor will throw exception if 
    cursor isnnot closed.

    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::disconnect session
    
    It disconnect from database.

    It returns 1 on success, otherwise it throws an expection.

- ::IngTcl::quote str
    
    ::IngTcl::quote returns quoted string, it can be used in statement without
    placeholders.

- ::IngTcl::dbms_name session

    Returns name of the RDBMS that you are connected to. It will return 
    "Vectorwise" or "Ingres" or "unknown".

- ::IngTcl::dbms_version session

    Returns version of the RDBMS that you are connected to. It will return 
    "unknown" on failure.

- ::IngTcl::is_vectorwise session

    Returns 1 if you are connected to Vectorwise, otherwise it returns 0.

7. Examples
===========

##### FIRST EXAMPLE #####

# This example script fetches all rows from table 'lol'

package require IngTcl

set session [::IngTcl::connect {somedb}]

set cursor [::IngTcl::prepare $session "select * from lol"]
::IngTcl::execute $session $cursor

set columns [::IngTcl::fetch_column_names $session $cursor]

set row 0
while {![::IngTcl::is_cursor_closed $session $cursor]} {
    set list [::IngTcl::fetch_row $session $cursor]
    if {[llength $list] > 0} { # Check if list is not empty
        set column 0
        puts {~~~~~~~~~}
        puts "Row: $row"
        puts {~~~~~~~~~}
        foreach value $list {
            puts "[lindex $columns $column] => $value"
            incr i
        }
    }
    incr row
}


##### SECOND EXAMPLE #####

# It does exactly the same thing as first example, but this time we're not using
# ::IngTcl::is_cursor_closed

package require IngTcl

set session [::IngTcl::connect {demodb}]

set cursor [::IngTcl::prepare $session "select * from lol"]

::IngTcl::execute $session $cursor

set columns [::IngTcl::fetch_column_names $session $cursor]

set row 0
while {[llength [set list [::IngTcl::fetch_row $session $cursor]]] > 0} {
    set column 0
    puts {---------}
    puts "Row: $row"
    puts {---------}
    foreach value $list {
        puts "[lindex $columns $column] => $value"
        incr i
    }
    incr row
}