Version 2 of IngTcl

Updated 2012-10-27 21:05:52 by xenu

IngTcl is an Actian Ingres and Actian Vectorwise database driver for Tcl. You can download it from CodePlex

README:


                      IngTcl 0.2 - 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 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\tcl(version), for example:
     "C:\Tcl\lib\tcl8.5"
   - 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:

- Ingres 10.1 Community Build 121 + Windows + Visual C++ on x86
- Ingres 10.1 Community Build 121 + Windows + Visual C++ on x64
- Ingres 10.1 Community Build 121 + Linux + gcc on x86
- Ingres 10.1 Community Build 121 + Linux + gcc on x64

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

- IngTcll::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
}