GitHub - nixinwang/python-ingresdbi at 38a7adb4bb4546c5d559cf9b38a1174f098b6dc5

Branches Tags
Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
dbi		dbi
hdr		hdr
tests		tests
CHANGELOG		CHANGELOG
LICENSE		LICENSE
PKG-INFO		PKG-INFO
README.html		README.html
README.txt		README.txt
setup.py		setup.py
Repository files navigation

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
  <META name="generator" content=
  "HTML Tidy for Linux/x86 (vers 31 October 2006), see www.w3.org">
  <TITLE>Ingres Python DBI Driver Version 2.0.1</TITLE>
  <META http-equiv="Content-Type" content="text-html; charset=utf-8">
  <STYLE type="text/css">
  <!--
            BODY
            {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-size: 80%;
                font-weight: normal;
                counter-reset: h1_no;
            }
            TABLE
            {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-size: 100%;
                color: 000000;

            }
            P
            {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-weight: normal;
      
            }
            H2:before 
            {
                content: counter(h1_no) ".0 ";
                counter-increment: h1_no;  /* Add 1 to h1_no */
            }
            H3:before 
            {
                content: counter(h1_no) "." counter(h2_no) " ";
                counter-increment: h2_no;
            }
            H1
            {
                font-size: 180%;
                font-weight: bold;
                color: #336699;
            }
            H2
            {
                font-size: 155%;
                font-weight: normal;
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                color: #336699 ;
                counter-reset: h2_no;
            }
            H3                           
            {
                font-size: 130%;
                font-weight: bold;
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                color: #336699 ;
                counter-reset: h3_no;
            }
            H4                           
            {
                font-size: 130%;
                font-weight: bold;
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                color: #336699;
            }
            A:link                       {
                text-decoration: underline;
                font-weight: bold;
                color: #336699;
            }
            A:visited                    {
                text-decoration: underline;
                font-weight: bold;
                color: #336699;
            }
            ol 
            {
                list-style-type: decimal;
                font-family:"Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
            }
            ol.toc_l1 
            {
                counter-reset: toc_l1 
            }
            ol.toc_l2 
            {
                counter-reset: toc_l2 
            }
            ul
            {
                list-style-type: disc;
                font-family:"Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
            }
            li                           
            {
                font-family:"Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
            }
            li.toc_l1:before
            {
                content: counter(toc_l1) ".0 "; counter-increment: toc_l1
            }
            li.toc_l2:before
            {
                content: counter(toc_l1) "." counter(toc_l2) " " ; counter-increment: toc_l2
            }
            li.toc_l1, li.toc_l2                       
            {
                font-family:"Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                color:#336699;
                font-weight:bold;
                display: block;
            }
            B                            
            {
                font-weight: bold  
            }
            STRONG                       
            {
                font-weight: bold  
            }
            I                            
            {
                font-style: italic  
            }
            EM                           
            {
                font-style: italic  
            }
            INPUT                        
            {
                color: #336699;
                 font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                 font-size: 90%;
            } /* Special */
            TEXTAREA                     
            {
                color: #336699;
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-size: 90%;
            } /* Special */
            BLOCKQUOTE                   
            {
                font-size: 80%;
            }
            PRE, CODE
            {
                font-family: "courier new", courier, monospace;
                font-size: 100%  
            }
            table, td                    
            {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-weight: normal;
                color: #000000;
                vertical-align: top;
                border: 1px solid #EBEBEB;
                border-collapse: collapse;
                font-size: 12px;
                padding: 2px;
            }
            table.invis, td.invis
            {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-weight: normal;
                color: #000000;
                vertical-align: middle;
                border: 0px;
                border-collapse: collapse;
                font-size: 12px;
                padding: 2px;
            }
            th
            {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                font-weight: bold;
                color: #000000;
                vertical-align: top;
                border: 1px solid #FFFFFF;
                background-color: #006699;
                color:#FFFFFF;
                text-align: left;
                padding: 2px;
            }
            tr.alt
            {
                background-color : #F1F5FA;
            }
            .ingrescorp               {
                font-family: Verdana, "Bitstream Vera Sans", Arial, Helvetica, Sans Serif;
                color: #FFFFFF;
                text-decoration: none;
                background-color: #336699;
                font-size: 130%;
                font-weight: bold;
            }
            hr
            {
                color: #CCCCCC; height:1px;
            }
        -->
  </STYLE>
</HEAD>

<BODY>
  <H1><A name="ingres_python_dbi_driver_version_2.0.1" id=
  "ingres_python_dbi_driver_version_2.0.1">Ingres Python DBI Driver Version
  2.0.1</A></H1>
  <HR>

  <OL CLASS="toc_l1">
    <LI class="toc_l1">
      <B><A href="#welcome">Welcome</A></B>

      <OL CLASS="toc_l2">
        <LI class="toc_l2"><A href="#new_in_this_release">New in This
        Release</A></LI>
      </OL>
    </LI>

    <LI class="toc_l1"><B><A href="#operating_system_support">Operating System
    Support</A></B></LI>

    <LI class="toc_l1"><B><A href="#installation_considerations">Installation
    Considerations</A></B></LI>

    <LI class="toc_l1">
      <B><A href="#general_considerations">General Considerations</A></B>

      <OL CLASS="toc_l2">
        <LI class="toc_l2"><A href="#features_not_included">Features Not
        Included</A></LI>

        <LI class="toc_l2"><A href=
        "#syntax_for_the_ingresdbi_connect_method">Syntax for the
        ingresdbi.connect() Method</A></LI>

        <LI class="toc_l2"><A href=
        "#syntax_for_the_ingres_extension_cursor_prepared_attribute">Syntax
        for the Ingres Extension Cursor.prepared Attribute</A></LI>
      </OL>
    </LI>

    <LI class="toc_l1">
      <B><A href=
      "#building_and_installing_the_ingres_python_dbi_driver">Building and
      Installing the Ingres Python DBI Driver</A></B>

      <OL CLASS="toc_l2">
        <LI class="toc_l2"><A href="#building_the_driver">Building the
        Driver</A></LI>

        <LI class="toc_l2"><A href="#installing_the_driver">Installing the
        Driver</A></LI>
      </OL>
    </LI>

    <LI class="toc_l1"><B><A href="#example_code">Example Code</A></B></LI>

    <LI class="toc_l1">
      <B><A href="#known_issues">Known Issues</A></B>

      <OL CLASS="toc_l2">
        <LI class="toc_l2"><B><A href="#generic_issues">Generic Issues</A></B></LI>

        <LI class="toc_l2"><B><A href="#windows_issues">Windows Issues</A></B></LI>
      </OL>
    </LI>

    <LI class="toc_l1"><B><A href="#support">Support</A></B></LI>
  </OL>
  <HR>

  <H2><A name="welcome" id="welcome">Welcome</A></H2>

  <P>This README contains all the documentation on the Ingres Python DBI
  driver.</P>

  <P>Please review this README before building or installing this software. We
  encourage users to test the software and provide feedback.</P>
  <HR>

  <H3><A name="new_in_this_release" id="new_in_this_release">New in This
  Release</A></H3>

  <P>The following changes have been made to the driver since its last
  release:</P>

  <UL>
    <LI>Raise IOError if the trace file cannot be opened</LI>

    <LI>Extend search for odbcinst.ini</LI>
  </UL>

  <P>See the <I>CHANGELOG</I> for a complete listing of all changes.</P>
  <HR>

  <H2><A name="operating_system_support" id=
  "operating_system_support">Operating System Support</A></H2>

  <P>This Ingres Python DBI driver supports all of the platforms supported by
  Ingres, including:</P>

  <UL>
    <LI>Solaris</LI>

    <LI>HP-UX</LI>

    <LI>AIX</LI>

    <LI>Linux</LI>

    <LI>Windows</LI>

    <LI>SCO UnixWare</LI>

    <LI>SCO OpenServer</LI>
  </UL>
  <HR>

  <H2><A name="installation_considerations" id=
  "installation_considerations">Installation Considerations</A></H2>

  <P>To build and install the Ingres Python DBI interface, the following
  components are needed:</P>

  <UL>
    <LI>Ingres r3 or above, including Ingres 2006. For a list of binary
    downloads, see <A href="http://www.ingres.com" target=
    "_blank">http://www.ingres.com</A>. For a source listing if you wish to
    build Ingres from source code, see <A href="http://www.ingres.com" target=
    "_blank">http://www.ingres.com</A>.</LI>

    <LI>C compiler (for example, GNU/C or Microsoft Visual Studio)</LI>

    <LI>Python interpreter version 2.4 or above</LI>

    <LI>The Ingres Python DBI source code</LI>
  </UL>
  <HR>

  <H2><A name="general_considerations" id="general_considerations">General
  Considerations</A></H2>

  <H3><A name="features_not_included" id="features_not_included">Features Not
  Included</A></H3>

  <P>The following features are currently not included in the Ingres Open
  Source Python DBI driver:</P>

  <UL>
    <LI>Connection pooling (non-Windows only)</LI>

    <LI>The following extended Cursor attributes and methods:

      <UL>
        <LI>messages</LI>

        <LI>lastrowid</LI>

        <LI>scroll</LI>
      </UL>
    </LI>

    <LI>Due to the limitations of the Ingres ODBC driver, the following items
    are not supported:

      <UL>
        <LI>Executing functions asynchronously</LI>

        <LI>Cursor direction other than forward-only</LI>

        <LI>Support for Ingres SQL command "COPY TABLE"</LI>

        <LI>Support for Ingres SQL command "SAVEPOINT"</LI>
      </UL>
    </LI>

    <LI>Due to syntax limitations of the Cursor.callproc() method, BYREF and
    output parameters are not supported in stored procedures. Row-returning
    procedures, however, are supported.</LI>
  </UL>
  <HR>

  <H3><A name="syntax_for_the_ingresdbi_connect_method" id=
  "syntax_for_the_ingresdbi_connect_method">Syntax for the ingresdbi.connect()
  Method</A></H3>

  <P>Connection objects are constructed using the ingresdbi.connect() method.
  The following keywords are valid:</P>

  <TABLE>
    <TR>
      <TH>Keyword</TH>

      <TH>Description</TH>
    </TR>

    <TR>
      <TD>dsn</TD>

      <TD>the ODBC Data Source Name</TD>
    </TR>

    <TR>
      <TD>database</TD>

      <TD>the target database</TD>
    </TR>

    <TR>
      <TD>connectstr</TD>

      <TD>alternate connection string</TD>
    </TR>

    <TR>
      <TD>vnode</TD>

      <TD>vnode definition as defined in the Ingres netutil utility. For more
      information, see the <A href=
      "http://docs.ingres.com/connectivity/">Ingres Connectivity
      Guide</A></TD>
    </TR>

    <TR>
      <TD>uid</TD>

      <TD>user login ID</TD>
    </TR>

    <TR>
      <TD>pwd</TD>

      <TD>user password</TD>
    </TR>

    <TR>
      <TD>servertype</TD>

      <TD>the type of the target database</TD>
    </TR>

    <TR>
      <TD>trace</TD>

      <TD>enables optional tracing of the DBI driver</TD>
    </TR>

    <TR>
      <TD>rolename</TD>

      <TD>role name</TD>
    </TR>

    <TR>
      <TD>rolepwd</TD>

      <TD>role password</TD>
    </TR>

    <TR>
      <TD>group</TD>

      <TD>group</TD>
    </TR>

    <TR>
      <TD>dbms_pwd</TD>

      <TD>DBMS password</TD>
    </TR>

    <TR>
      <TD>selectloops</TD>

      <TD>fetches using select loops instead of the default cursor loops</TD>
    </TR>

    <TR>
      <TD>autocommit</TD>

      <TD>whether autocommit is enabled. Autocommit is off by default</TD>
    </TR>

    <TR>
      <TD>catschemanull</TD>

      <TD>whether to disable underscores in wildcard searches</TD>
    </TR>

    <TR>
      <TD>catconnect</TD>

      <TD>whether to use separate sessions for catalog operations</TD>
    </TR>

    <TR>
      <TD>numeric_overflow</TD>

      <TD>whether to ignore or fail numeric overflows</TD>
    </TR>
  </TABLE>

  <P>If the "dsn" keyword is specified, the other keywords are optional. If
  the database is specified, the other keywords are optional. If the vnode
  keyword is specified, and the connection is local, the value "(LOCAL)" can
  be used as the vnode definition, or the vnode attribute can be omitted.</P>

  <P>If the "connectstr" keyword is specified, the other keywords are
  optional. The "connectstr" keyword specifies an ODBC connection string. For
  examples of valid Ingres ODBC connection strings, see the <A href=
  "http://docs.ingres.com/connectivity/">Ingres Connectivity Guide</A>.</P>

  <P>All of the above keywords reference string values except for the "trace"
  keyword. The "trace" keyword references a tuple with two members. The first
  member is the tracing level, which can be a value of 0 through 7. The second
  member is a string that describes the trace file. If the second member has a
  value of "None", the tracing is written to the standard output.</P>

  <P>The following values are valid for the "autocommit", "selectloops",
  "catconnect", "catschemanull", and "numeric_overflow" keyword
  attributes:</P>

  <UL>
    <LI>"on"</LI>

    <LI>"off"</LI>

    <LI>"y"</LI>

    <LI>"n"</LI>

    <LI>"Yes"</LI>

    <LI>"No"</LI>
  </UL>

  <P>The following values are valid for the "servertype" keyword:</P>

  <UL>
    <LI>"INGRES"</LI>

    <LI>"DCOM"</LI>

    <LI>"IDMS"</LI>

    <LI>"DB2"</LI>

    <LI>"IMS"</LI>

    <LI>"ODBC"</LI>

    <LI>"VSAM"</LI>

    <LI>"RDB"</LI>

    <LI>"STAR"</LI>

    <LI>"RMS"</LI>

    <LI>"ORACLE"</LI>

    <LI>"INFORMIX"</LI>

    <LI>"SYBASE"</LI>

    <LI>"MSSQL"</LI>

    <LI>"DB2UDB"</LI>
  </UL>

  <P>If "INGRES" is not specified, the "servertype" values require access to
  an Ingres (that is, Enterprise Access) or EDBC gateway server. Otherwise, no
  gateway is required. The default is "INGRES".</P>

  <P>Select loops usually have the best performance. However, only one select
  loop can be active at a time. Cursor loops support unlimited multiple active
  result sets, but can be slower in performance.</P>

  <P>Following is an example of a valid instantiation of the ingresdbi
  connection object, using all keywords:</P>
  <PRE>
    conn = ingresdbi.connect(dsn ="myDSN",
            database  "myDB",
            vnode = "(LOCAL)",
            uid = "myUID",
            pwd = "myPWD",
            dbms_pwd = "myDbmsPWD",
            group = "myGroup",
            rolename = "myRoleName",
            rolepwd = "myRolePwd",
            selectloops = "Y",
            autocommit = "Y",
            servertype = "INGRES",
            driver = "Ingres",
            catschemanull = "off",
            catconnect = "Off",
            numeric_overflow = "yes",
            connectStr = "DSN=myDSN",
            trace = (7, "dbi.log")
            )
            
</PRE>

  <P>Connection objects can be constructed without keywords. If keywords are
  not used, arguments must follow the order: dsn, database, vnode, uid, pwd,
  selectloops, autocommit, servertype, and trace. An example without keywords
  is shown here:</P>
  <PRE>
    conn = ingresdbi.connect(
            "myDSN",
            "myDB",
            "(LOCAL)",
            "MnyUID",
            "myPWD",
            "Y",
            "Yes",
            "INGRES",
            "Ingres 3.0",
            "myRoleName",
            "myrolePWD",
            "myGroup",
            "n",
            "NO",
            "YES",
            "yes",
            "N",
            "myDbmsPwd",
            "DSN=myDSN",
            (7,"dbi.log")
            )
            
</PRE>
  <HR>

  <H3><A name="syntax_for_the_ingres_extension_cursor_prepared_attribute" id=
  "syntax_for_the_ingres_extension_cursor_prepared_attribute">Syntax for the
  Ingres Extension Cursor.prepared Attribute</A></H3>

  <P>Although PEP 249 requires all queries to be prepared, the Ingres DBI
  driver does not prepare queries by default. Instead, the Cursor attribute
  "prepared" can be deployed.</P>

  <P>If Cursor.prepared is set to "y", "yes", or "on", subsequent queries
  specified in the Cursor.execute() or Cursor.executemany() methods are
  executed as prepared. However, only one query string is allowed for each
  cursor instantiation. If the query string is changed, a warning is issued,
  and the Ingres DBI driver resorts to direct query execution.</P>

  <P>The Cursor.callproc() method raises an exception if the Cursor.prepared
  attribute is set to "y", "yes", or "on".</P>

  <P>The following values (entered in either uppercase or lowercase) are valid
  for the Cursor.prepared attribute:</P>

  <UL>
    <LI>"on"</LI>

    <LI>"off"</LI>

    <LI>"y"</LI>

    <LI>"n"</LI>

    <LI>"Yes"</LI>

    <LI>"No"</LI>
  </UL>
  <HR>

  <H2><A name="building_and_installing_the_ingres_python_dbi_driver" id=
  "building_and_installing_the_ingres_python_dbi_driver">Building and
  Installing the Ingres Python DBI Driver</A></H2>

  <H3><A name="building_the_driver" id="building_the_driver">Building the
  Driver</A></H3>

  <P>The build process has been simplified by the use of the Python <A href=
  "http://docs.python.org/lib/module-distutils.html">DistUtils package</A>.
  Start the build process by extracting the necessary files from the Ingres
  DBI compressed archive:</P>

  <H4>Mac OS X, Linux and Unix</H4>

  <OL>
    <LI>Extract the files from ingresdbi-2.0.1.tar.gz:
      <PRE>
    gzip -cd ingresdbi-2.0.1.tar.gz | tar zvf -
</PRE>or if you have GNU tar:
      <PRE>
    tar zxvf ingresdbi-2.0.1.tar.gz
</PRE>
    </LI>

    <LI>Enter the newly created source directory,
    <CODE>ingresdbi-2.0.1</CODE>:
      <PRE>
    cd ingresdbi-2.0.1
</PRE>
    </LI>

    <LI>Initiate the build process.
      <PRE>
    python setup.py build
</PRE>
    </LI>
  </OL>

  <H4>Windows</H4>

  <UL>
    <LI>Use WinZip (or similar product) to extract the directories and files
    from ingresdbi-2.0.1.zip.

      <UL>
        <LI>Cygwin users can use either of the commands for <I>Mac OS X, Linux
        and Unix</I></LI>
      </UL>
    </LI>

    <LI>Enter the newly created source directory,
    <CODE>ingresdbi-2.0.1</CODE>:
      <PRE>
    cd ingresdbi-2.0.1
</PRE>
    </LI>

    <LI>Initiate the build process.
      <PRE>
    python setup.py build
</PRE>
    </LI>
  </UL>

  <P><B>Note:</B> You can skip this and jump straight to the install process
  as this will automatically build.</P>
  <HR>

  <H3><A name="installing_the_driver" id="installing_the_driver">Installing
  the Driver</A></H3>

  <P>As with the build process, the installation process makes use of
  DistUtils. By default, the Ingres Python DBI driver is installed into
  Python's site-packages directory. The ability to provide alternate
  installation locations has not been investigated at this time. The only
  requirement for installing is to be able to write to the site-packages
  directory.</P>

  <P>To install, execute the following command:</P>
  <PRE>
    python setup.py install
</PRE>

  <P>To create a deliverable source package, execute the following
  command:</P>
  <PRE>
    python setup.py sdist
</PRE>
  <HR>

  <H2><A name="example_code" id="example_code">Example Code</A></H2>

  <P>The following code provides a simple Python database example using the
  Ingres Python DBI driver:</P>
  <PRE>
    import ingresdbi
    import pprint
    """
    import os
    username=os.getenv('test_username')
    password=os.getenv('test_password')
    vnode=os.getenv('test_vnode')
    database=os.getenv('test_database')
    trace=None
    """
    enable_trace = 0
    if enable_trace == 1:
        trace=(7, None)
    else:
        trace=(0, None)
    database='iidbdb'
    vnode='(local)'
    prog_str = 'DEMO SIMPLE SELECT'
    print prog_str, "connecting to database: " + database 
    dc=ingresdbi.connect(database=database, vnode=vnode, trace=trace)
    print prog_str, "Creating new cursor()"
    c=dc.cursor()
    print prog_str, "About to call cursor.execute()"
    c.execute("select * from iidbconstants")
    print "cursor.description = "
    description = c.description
    pprint.pprint (description )
    print prog_str, "cursor.fetchall()"
    rows = c.fetchall()
    print "rows = ", rows
    row_count = 0
    for row in rows:
        row_count = row_count + 1
    print 'Row #', row_count
    count = 0
    for column in row:
        print description[count][0] , ': ', column
        count = count + 1
    print "-----------------------------"
    print prog_str, "connection.commit()"
    dc.commit()
    print prog_str, "connection.close()"
    dc.close()
</PRE>
  <HR>

  <H2><A name="known_issues" id="known_issues">Known Issues</A></H2>

  <H3><A name="generic_issues" id="generic_issues">Generic
  Issues</A></H3>

  <UL>
    <LI>There is no support for installing to an alternate directory other
    than the default site-packages.</LI>
  </UL>

  <H3><A name="windows_issues" id="generic_issues">Windows
  Issues</A></H3>

  <UL>
    <LI>
      <B>Python 2.3 only</B> - <CODE>python setup.py build</CODE> may fail
      with:
      <PRE>
    error: Python was built with version 6 of Visual Studio,
    and extensions need to be built with the same version of the
    compiler, but it isn't installed.
</PRE>

      <P>If you have Visual Studio version 6 installed, run Microsoft Visual
      C++ 6.0 <CODE>MSDEV.EXE</CODE> (the GUI), quit out, and then retry the
      build. For further information, see Python mailing list <A href=
      "http://mail.python.org/pipermail/python-dev/2003-November/040478.html"
      target=
      "_blank">http://mail.python.org/pipermail/python-dev/2003-November/040478.html</A>.</P>
    </LI>
  </UL>
  <HR>

  <H2><A name="support" id="support">Support</A></H2>

  <P>Support for the Python Ingres DBI interface is available from a number of
  different sources. Users with a support contract can either raise an issue
  via <A href=
  "https://servicedesk.ingres.com/">https://servicedesk.ingres.com/</A> or
  through their local technical support department. See <A href=
  "http://ingres.com/support" target="_blank">http://ingres.com/support</A>
  for a complete list of locations, primary service hours, and telephone
  numbers. Users without a support contract can post questions or problems to
  the Ingres Community Forums (<A href=
  "http://community.ingres.com/forums/viewforum.php?f=5">http://community.ingres.com/forums/viewforum.php?f=5</A>)
  or to comp.databases.ingres (<A href=
  "http://groups.google.com/group/comp.databases.ingres">http://groups.google.com/group/comp.databases.ingres</A>).</P>
  <HR>

  <P>Revision $Id$</P>

  <P>© 2008 Ingres Corporation. All rights reserved.</P><!--
Vim modeline directives
vim:tabstop=4 shiftwidth=4 expandtab fileencoding=utf-8
-->
</BODY>
</HTML>