Interactive COBOL ODBC Driver 5.60                     June-2026

Interactive COBOL provides a common development and runtime
environment on Windows and Linux that allows complete applications
(including code and data) to be moved from one system to another
without change.  As of version 5.60, only the 64-bit version of
the driver is available and installed.

Under Linux, the Interactive COBOL ODBC Driver provides
an ODBC-compliant interface via icodbc.so.  This interface can be
used with the unixODBC Driver Manager.  One program in particular
that makes use of this interface is the JDBC-ODBC Bridge under the
Java Runtime.  More can be found on this product at the end of this
readme.

Under Windows, the Interactive COBOL ODBC Driver (ICODBC32.DLL -
yes, thank Microsoft that it is named that even though it is 64-bit) for
Windows is a fully functional ODBC Driver (SQL-92 Entry level
compliant) providing access to Interactive COBOL data records stored
in INDEXED ORGANIZATION files.  Through this mechanism it is
possible for ODBC-enabled programs (e.g., Crystal Reports,
Visual Basic, PowerBuilder, Microsoft Access, etc...) to access
legacy Interactive COBOL INDEXED file data records as if they were
rows of a table of an SQL relational database.


General Information
-------------------

Under Windows, the Interactive COBOL ODBC Driver is accessible
from ODBC-enabled applications.  The Interactive COBOL ODBC Driver
was built using the Microsoft Visual Studio compiler with the
Microsoft Windows Kit (SDK) and the SYWARE Dr. DeeBee
ODBC Driver Kit (Gold Edition).  Portions of the product are
copyrighted by SYWARE Inc. and by Microsoft.

Under Windows, for the purpose of buffering file data within an
application, multiple opens of the same local/redirected file are
commoned by using the lower case rendition of the file name supplied
to the driver.  It is important to always specify the identical
filename (or alias) and not a different alias to refer to a
particular file.  This applies to database and table definition
files as well as data (INDEXED) file names.

Under Linux, the inode number is used for commoning instead of the filename.

On Linux and Windows, the Interactive COBOL ODBC Driver
optionally connects to the shared memory area created and
initialized by the Interactive COBOL System Executive Program
(ICEXEC).  Multi-user file sharing, buffering, and record locking
are handled more efficiently through this mechanism as opposed
to a stand-alone (single-user) environment.  This version of the
ODBC driver will only connect with shared memory areas created by
ICEXEC Revision 5.00 (and later); if an earlier version of the
shared memory area exists the driver will not connect.

To use the Interactive COBOL ODBC Driver, a valid ICOBOL ODBC Driver
license (ICODBCDR) must be available via the license server
(ICPERMIT).

(64-bit Windows)
The default ODBC interface, the one invoked from
the Control Panel, is 64-bit only.

(Auditing)
To enable auditing for the ICODBC driver set the ICODBC32 environment
variable as required.  Valid options are: [-a|A file] [-t] [-q].

For -a:p an audit log "icodbc_<pid>.lg" will be created in the current
directory for all connections.


Installation
------------

*   Under Windows, the Interactive COBOL ODBC Driver and related ODBC
    components can be installed as an optional component selection
    from the Interactive COBOL Master installation program.  In order
    to install it, you must select it from the "Select Components"
    setup dialog box by checking the box next to the "ODBC Driver"
    item.

*   Under Linux, the Interactive COBOL ODBC Driver is included in
    the master install file and also as a separate odbc-only install
    file.  See the Linux section further down in the readme for more
    information.

    The actual shared object can be made accessible to all programs
    via the installic script located in the install sub-directory.
    Just execute:

        install/installic icodbc

    This will install icodbc.so in the appropriate /usr/lib directory.

Changes in 5.60
---------------

1.  ICOBOL 5.60 is 64-bit only.  There are no 32-bit components.

Changes in 5.53
---------------

1.  There was a bug in command line options processing such that
    extended auditing options were not being processed.  The options
    would typically be set by setting the ICODBC32 environment variable.

Changes in 5.36
---------------

1.  The ODBC driver had a bug where it would return the error:
    "Invalid attribute identifier." for the SQLGetStmtAttr call with
    the SQL_ROWSET_SIZE option.

2.  The SQLGetInfo call with the SQL_DBMS_NAME will now return
    ICISAM32 or ICISAM64 instead of just ICISAM to indicate which
    driver is running.

Changes in 5.24
---------------

None.

Changes in 5.23.01
------------------

1.  Some older ODBC calls were inadvertently optimized out of our build
    because they were no longer directly referenced.


Changes in 5.23
---------------

1.  A number of ODBC 2 compatible calls that worked pre 5.xx
    were returning an error.  Some applications connecting as
    ODBC 3 applications still used the outdated calls and were
    failing.


Changes in 5.06 - 5.22
----------------------

None.


Changes in 5.05
---------------

1.  ICODBCDR could cause a memory fault or crash when setting
    data into columns, e.g., with an INSERT that used parameters.
    This bug was introduced in 4.80 and 5.00.


Changes in 5.01-5.04
--------------------

None.


Changes in 5.00
---------------

1.  Some sample files have been released in the examples/icodbc subdirectory
    that can be used to see a very simple .xdb/.xdt description for a
    simple isam file.

    These files are:  sample_odbc.xdb, sample_odbc.xdt,
    sample_file.xd, sample_file.nx


Changes previous to 5.00 can be found in the readic.txt file for the
most recent ICOBOL 4 release and it can be downloaded from the Archive
page on the website (www.icobol.com).


Notes and Warnings
------------------

Microsoft Access
----------------

If you use Access to link to a table only the first 101 records will be
retrieved.  If you had imported the table all the data is retrieved.
That is the default behavior for Jet, (the actual database engine under
Access) as to records returned when linking to an external data source.

You can:

a)  Position to the last record and hit Shift-F9 for the next block of
    records to be retrieved (usually in groups of 100 records but
    sometimes not) or

b)  Create/edit the Access configuration table MSysConf so that the
    default is greater.  See your Access documentation for more details.


Crystal Reports
---------------

If you are using Crystal Reports 9+ you may get an error message when
working with more that 1 table:

        failed to open a rowset
        Details:  42000: [Envry Corporation [ICOBOLODBC Driver]
        Unexpected extra token:  INNER

This is because Crystal did not generate an ODBC compliant SQL INNER JOIN
statement.  This is a known bug in revision 9.

Until Crystal fixes this, to get around the problem you can:

1)  go back to Crystal revision 8.5

2)  manually edit the SQL statement so that it conforms to the ODBC
    standard for an inner join.

Crystal has a tendency to generate SQL statements that are not ODBC
standard compliant.


Linux ICODBC Driver
------------------

The ICODBC Unix driver is intended to provide an ODBC interface to
those Linux applications that can make use of a shared object
interface to ODBC.  The ODBC "glue" logic under Linux is provided with
the unixODBC project.  unixODBC is available from www.unixodbc.org
and must be installed before using the ICODBC Unix driver (icodbc.so).
UnixODBC is not so much an end user program, but rather an
intermediary between a program (application) and one or more
databases.  It provides the ODBC Driver Manager and Administrator.
In this case the database is ICISAM files provided via icodbc.so.

The isql program that comes with unixODBC can be used to perform simple
connections and queries to test that ICODBC is installed correctly.

One application that makes use of the unixODBC project is the JDBC-ODBC
Bridge that is provided with the Java 2 Runtime environment.  A java
runtime can be downloaded from www.java.sun.com/products.  The JDBC-ODBC
Bridge enable java programs to access ODBC data when a JDBC compliant
interface is not avaliable to access the same data.

Under Java, the JDBC-ODBC Driver can be loaded with the

        ClassforName("sun.jdbc.odbc.JdbcodbcDriver")

A Connection to an ICOBOL Isam database can be made via:

        Connect con = DriverManager.getConnection( jdbc.odbc.<datasource>,
                        <username>, <userpassword> );

        where <datasource> is the DataSetName for the ICOBOL database.


unixODBC
--------

Getting Started

UnixODBC is available in source code only.  This means that you download
a tar file (or zipped tar file) from http://www.unixODBC.org, extract it,
compile it, and install it.


Installing unixODBC

As mentioned before, get the source tar file from http://www.unixodbc.org.
As root, move the tar file to /opt or /usr/local or where ever you want
the source to reside.  If zipped, then unzip the file.  Untar the file
and run the following commands from the command line in the unixODBC
source directory:

        ./configure
        make
        make install

Assuming that you have all the libraries and tools that it needs, you
should be breezing through this compile.  UnixODBC takes quite a while
to compile, actually all of these packages do.  Relax and enjoy it.
After installing you will probably have to set the path for shared
objects (LD_LIBRARY_PATH on Linux).


Installing

Prerequisets:


Under Linux, there is no ODBC Administrator so the data-sources must be
configured in a text file.

System versus User

ODBC distingushes between two types of ini files.  System ini files are
designed to be accessable but not modifable by any user, and user files
are private to a particular user, and may be modified by that user.
The system files are odbcinst.ini and odbc.ini (note no leading dot),
and the user file is ~/.odbc.ini in each user's home directory
(note leading dot).

The system file odbcinst.ini contains information about ODBC drivers
available to all users, and the odbc.ini file contains information
about DSN's available to all users.  These "System DSN's" are useful
for application such as web servers that may not be running as a real
user and so will not have a home directory to contain a .odbc.ini file.

A good example of this is Apache and PHP with ODBC support.  When the
http server is first started it calls SQLAllocEnv as root.  It then
at a later time changes to the specified user (in my case nobody) and
calls SQLConnect.  If the DSN's was not a system DSN then this fails.

The ~/.odbc.ini in the user's home directory are "User DSN's".  These
are only useful for cases of testing or when you do not need to share
datasets.

The unixODBC library uses the odbcinst.ini file to administrator the
driver manager.  Again this file is in a .ini format and has the
following format.

    odbcinst.ini
    ------------

    This ini file simply lists all installed drivers.  It is located
    in /usr/local/etc/odbcinst.ini.  The syntax is simple; a name
    followed by a property which tells us the drivers file name.
    For example;

        [Sybase 11]
        Comment = Super Duper Sybase Server
        Driver =  /usr/lib/libsybase.so
        Setup = /usr/lib/libsybaseS.so
        FileUsage = 1

    The Driver file name ( i.e., /usr/lib/libsybase.so ) should be unique.
    The friendly name ( i.e., Sybase 11 ) must also be unique.

    The Setup property points to a shared object containing functions to
    be called by ODBC Config.  ODBC Config will call this share to get
    driver specific property names during data source configuration.
    If ODBC Config can not find/use this file it will assume some
    defaults such as; Data Source Name, Host, and default Database.
    (Setup is NOT SUPPORTED BY ICODBC at this time.)

    One can modify this file either using the ODBCINST shared object,
    by using the command line equivalent odbcinst, or a standard Linux
    text editor.

    The odbcinst command can be used to add ICODBC to this file.
    Enter the following into a temp file:

        [ICODBC]
        Comment   = Interactive COBOL ISAM ODBC Driver for Linux
        Driver    = icodbc.so
        FileUsage = 1

	Note that you must have permission to write to the appropriate
	file so generally this would be run as superuser.

    Now invoke odbcinst with the following arguments assuming you
    have created the above file template_icodbc:

        "odbcinst -i -d -f template_icodbc"

    The args to odbcinst are as follows:

        -i (install)
        -d (driver name)
        -f (name of template)

    Make sure you copy or link the released file, icodbc.so, to
    /usr/lib.  If you had specified a simple name in the Driver line
    above, then the path for shared objects can be used to find
    the icodbc driver. (LD_LIBRARY_PATH under Linux.)  You can
    use the installso script in the install sub-directory of the
    icobol release to install icodbc.so. Just execute:

        "install/installso icodbc".

    If you wish to turn on ODBC tracing then the following needs to
    be added to the odbcinst.ini file:

        [ODBC]
        Trace = Yes
        Trace File = filename

    If not specified, Trace defaults to NO and Trace File defaults to
    /tmp/sql.log.


    odbc.ini or ~/.odbc.ini
    -----------------------

    These files describe the data-set to be used.  They have the same
    format but refer to SystemDSN and UserDSN's respectively.
    The environment variable ODBCSYSINI can be used to find the
    system odbc.ini file and the environment variable HOME is used
    to find the user .odbc.ini file.  If the system file is not found
    then the "$HOME"/.odbc.ini file is tried.  If it is not found
    then the ODBC call will fail on the DriverConnect.  Thus you must
    have ODBCSYSINI set if you are not using UserDSN's.

    The contents of the odbc.ini files give a section that is the
    data-set name, then a description, driver, and the DBQ (database)
    entry.  Generally each driver requires different entries.
    The entries may be added in the same way using odbcinst, or
    a text editor.  A sample entry to match the above driver
    could be

        [TESTDSN]
        Description         = Test IC Dataset
        Driver              = ICODBC
        DBQ                 = /home/data/datafile89
        UID                 = user-id
        PWD                 = user-password
        Threading           = 3

    And this may be written to a template file, and inserted in the
    ini file for the current user by:

       "odbcinst -i -s -f template_file"

    The individual entries of course may vary.

    The Driver line is used to match the [section] entry in the
    odbcinst.ini file and the Driver line in the odbcinst
    file and is used to find the path for the driver library, and
    this is loaded and the connection is then established.
    It's possible to replace the driver entry with a path to the
    driver itself.  This can be used, for example if the user can't
    get root access to setup anything in /etc (less important now
    because of the movable etc path).

    The DBQ line specifies the actual ICISAM database file to open.
    UID/PWD specify the user-id and password if any are required to
    access the database.

    The Threading line instructs unixODBC to not allow any
    threading.  This should be the default.  Threading sets the
    level of protection from threading for the driver and can be
    from 0 - 3.  0 is no protection, 1 is protect at the statement
    level, 2 is protect at the DBC level, 3 is protect at the
    environment level (i.e. no threading at all).


The Unix ICODBC driver has been tested under various Linux (Intel)
revisions.

The isql command that comes with unixODBC can be used to connect
to a dataset and execute some simple SQL commands.


ERROR CONDITIONS
----------------

A.  You get:

    Error: Connection refused (oserr=111) Connecting to localhost:7334
    java.sql.SQLException:[unixODBC]

Icpermit is not running.

B.  You get:

    java.sql.SQLException: No suitable driver

The unixODBC driver(s) cannot be found.  Make sure the load path
for .so files is set.  (Under Linux, LD_LIBRARY_PATH=/usr/local/lib).

C.  You get:

    Warning: The file was not found (oserr=2): messages/system.ms
        Proceeding without messages

ICROOT is not set.

D.  You get:

    java.sql.SQLException: [unixODBC]

The icodbc.so driver cannot find "$ODBCSYSINI"/odbc.ini
or "$HOME"/.odbc.ini to find the data set name.


You must have an ICODBC license available from the license manager.



End of Readodbc
