Interactive COBOL ODBC Driver 5.24 30-Dec-2016 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. Both 32-bit and 64-bit versions of the driver are available based on the version of ICOBOL 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) 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) version 8.0 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) If you're using 64-bit Windows and want to edit the configuration of the 32-bit ODBC drivers, you can do this by launching the program %SystemRoot%\SysWOW64\odbcad32.exe, which brings up the 32-bit ODBC console. The default ODBC interface, the one invoked from the Control Panel, is 64-bit only. For your convenience, shortcuts to both administrators is created in the ICOBOL start menu folder at install time. (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_.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. On 64-bit Windows, both the 32-bit and the 64-bit drivers will be installed. * Under Linux, the Interactive COBOL ODBC Driver is included in the master install file and also as a separate odbc-only install file. The 64-bit install files also include the 32-bit ODBC driver, located in the x86 sub-directory. 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.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., , ); where 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